java 68 lines · 9 steps

Building a resilient RestClient in Spring

A Spring @Configuration bean assembles a RestClient with timeouts and a retry interceptor that backs off on transient failures.

Explained by highlit

Spring Intermediate retry http-client backoff interceptor resilience

1@Configuration
2public class PaymentGatewayClientConfig {
3 
  @Bean
  RestClient paymentGatewayClient(RestClient.Builder builder,
                                  @Value("${payment.gateway.base-url}") String baseUrl) {
      var requestFactory = new SimpleClientHttpRequestFactory();
      requestFactory.setConnectTimeout(Duration.ofSeconds(2));
      requestFactory.setReadTimeout(Duration.ofSeconds(5));
10 
      return builder
              .baseUrl(baseUrl)
              .requestFactory(new BufferingClientHttpRequestFactory(requestFactory))
              .requestInterceptor(new RetryInterceptor(3, Duration.ofMillis(200)))
              .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)
              .build();
  }
18 
  static class RetryInterceptor implements ClientHttpRequestInterceptor {
20 
      private static final Logger log = LoggerFactory.getLogger(RetryInterceptor.class);
      private static final Set<Integer> RETRYABLE = Set.of(429, 502, 503, 504);
23 
      private final int maxAttempts;
      private final Duration backoff;
26 
      RetryInterceptor(int maxAttempts, Duration backoff) {
          this.maxAttempts = maxAttempts;
          this.backoff = backoff;
      }
31 
      @Override
      public ClientHttpResponse intercept(HttpRequest request, byte[] body,
                                          ClientHttpRequestExecution execution) throws IOException {
          IOException lastError = null;
          for (int attempt = 1; attempt <= maxAttempts; attempt++) {
              try {
                  ClientHttpResponse response = execution.execute(request, body);
                  if (attempt == maxAttempts || !RETRYABLE.contains(response.getStatusCode().value())) {
                      return response;
                  }
                  log.warn("Retrying {} {} after status {} (attempt {}/{})",
                          request.getMethod(), request.getURI(), response.getStatusCode(), attempt, maxAttempts);
                  response.close();
              } catch (IOException ex) {
                  lastError = ex;
                  if (attempt == maxAttempts) {
                      throw ex;
                  }
                  log.warn("Retrying {} {} after I/O error (attempt {}/{}): {}",
                          request.getMethod(), request.getURI(), attempt, maxAttempts, ex.getMessage());
              }
              sleep(backoff.multipliedBy(attempt));
          }
          throw Objects.requireNonNullElseGet(lastError,
                  () -> new IOException("Exhausted retries for " + request.getURI()));
      }
58 
      private void sleep(Duration duration) throws IOException {
          try {
              Thread.sleep(duration.toMillis());
          } catch (InterruptedException ex) {
              Thread.currentThread().interrupt();
              throw new IOException("Retry interrupted", ex);
          }
      }
  }
68}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Centralizing HTTP client setup in a @Bean makes timeouts, headers, and retries consistent across every caller.
2A request interceptor is the right seam for cross-cutting concerns like retry, since it wraps the actual execution.
3Only retry idempotent-safe transient statuses with backoff, and always surface the last error when attempts are exhausted.

Related explainers

java

@Component
@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {

Transparent column encryption in Spring & JPA

encryption aes-gcm jpa-converter

Advanced 10 steps

java

package com.acme.billing.config;
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.ConfigurationProperties;

Feature-flagged beans with Spring @ConditionalOnProperty

feature-flags conditional-beans strategy-pattern

Intermediate 5 steps

java

public static Map<String, String> parseCookieHeader(String header) {
    Map<String, String> cookies = new LinkedHashMap<>();
    if (header == null || header.isBlank()) {
        return cookies;

Parsing an HTTP Cookie header in Java

string-parsing http url-decoding

Intermediate 6 steps

java

public class TimedSocketReader {
 
    private static final int READ_TIMEOUT_MS = 5_000;
    private static final int CONNECT_TIMEOUT_MS = 3_000;

Reading a socket with connect and read timeouts

sockets timeouts io

Intermediate 8 steps

java

public final class EncodingDetector {
 
    public enum Encoding {
        UTF_8, UTF_16LE, UTF_16BE, UTF_32LE, UTF_32BE, ASCII, UNKNOWN

Detecting text encoding from raw bytes in Java

byte-manipulation encoding-detection bitwise-operations

Intermediate 8 steps

java

public final class ImportOrganizer {
 
    private static final Pattern IMPORT_LINE =
            Pattern.compile("^import\\s+(static\\s+)?([\\w.]+(?:\\.\\*)?)\\s*;\\s*$");