Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Introduction

Calling external services through the REST endpoint is a common activity that was made very straightforward by libraries like Feign. However, a lot of things can go wrong during such calls. Many of these problems are random or temporary.

In this tutorial, we’ll learn how to retry failed calls and make more resilient REST clients.

2. Feign Client Setup

First, let’s create a simple Feign client builder that we’ll later enhance with retrying features. We’ll use OkHttpClient as the HTTP client. Also, we’ll use GsonEncoder and GsonDecoder for encoding and decoding the requests and the responses. Finally, we’ll need to specify the target’s URI and response type:

public class ResilientFeignClientBuilder {
    public static <T> T createClient(Class<T> type, String uri) {
        return Feign.builder()
          .client(new OkHttpClient())
          .encoder(new GsonEncoder())
          .decoder(new GsonDecoder())
          .target(type, uri);
    }
}

Alternatively, if we use Spring, we could let it auto-wire Feign client with available beans.

3. Feign Retryer

Fortunately, retrying abilities are baked in Feign, and they just need to be configured. We can do that by providing an implementation of the Retryer interface to the client builder.

Its most important method, continueOrPropagate, accepts RetryableException as an argument and returns nothing. Upon execution, it either throws an exception or exits successfully (usually after sleeping). If it doesn’t throw an exception, Feign will continue to retry the call. If the exception is thrown, it’ll be propagated and will effectively finish the call with an error.

3.1. Naive Implementation

Let’s write a very simple implementation of Retryer that will always retry calls after waiting one second:

public class NaiveRetryer implements feign.Retryer {
    @Override
    public void continueOrPropagate(RetryableException e) {
        try {
            Thread.sleep(1000L);
        } catch (InterruptedException ex) {
            Thread.currentThread().interrupt();
            throw e;
        }
    }
}

Because Retryer implements the Cloneable interface, we also needed to override the clone method.

@Override
public Retryer clone() {
    return new NaiveRetryer();
}

Finally, we need to add our implementation to client builder:

public static <T> T createClient(Class<T> type, String uri) {
    return Feign.builder()
      // ...
      .retryer(new NaiveRetryer())    
      // ...
}

Alternatively, if we are using Spring, we could annotate NaiveRetryer with @Component annotation or define a bean in the configuration class and let Spring do the rest of the work:

@Bean
public Retryer retryer() {
    return new NaiveRetryer();
}

3.2. Default Implementation

Feign provides a sensible default implementation of the Retryer interface. It’ll retry only a given number of times, will start with some time interval, and then increase it with each retry up to provided maximum. Let’s define it with starting interval of 100 milliseconds, the maximum interval of 3 seconds, and the maximum number of attempts of 5:

public static <T> T createClient(Class<T> type, String uri) {
    return Feign.builder()
// ...
      .retryer(new Retryer.Default(100L, TimeUnit.SECONDS.toMillis(3L), 5))    
// ...
}

3.3. No Retrying

If we don’t want Feign to ever retry any calls, we can provide Retryer.NEVER_RETRY implementation to the client builder. It’ll simply propagate the exception every time.

4. Creating Retryable Exceptions

In the previous section, we learned to control how often we retry calls. Now let’s see how to control when we want to retry the call and when we want to simply throw the exception.

4.1. ErrorDecoder and RetryableException

When we receive an erroneous response, Feign passes it to an instance of the ErrorDecoder interface that decides what to do with it. Most importantly, the decoder can map an exception to an instance of RetryableException, enabling Retryer to retry the call. The default implementation of ErrorDecoder only creates a RetryableExeception instance when the response contains the “Retry-After” header. Most commonly, we can find it in 503 Service Unavailable responses.

That’s good default behavior, but sometimes we need to be more flexible. For example, we could be communicating with an external service that, from time to time, randomly responds with 500 Internal Server Error, and we have no power to fix it. What we can do is to retry the call because we know that it’ll probably work next time. To achieve that, we’ll need to write a custom ErrorDecoder implementation.

4.2. Creating Custom Error Decoder

There is only one method that we need to implement in our custom decoder: decode. It accepts two arguments, a String method key, and a Response object. It returns an exception, should it be an instance of RetryableException or some other exception that depends on the implementation.

Our decode method will simply check if the response’s status code is higher or equal to 500. If that’s the case, it’ll create RetryableException. If not, it will return basic FeignException created with the errorStatus factory function from the FeignException class:

public class Custom5xxErrorDecoder implements ErrorDecoder {
    @Override
    public Exception decode(String methodKey, Response response) {
        FeignException exception = feign.FeignException.errorStatus(methodKey, response);
        int status = response.status();
        if (status >= 500) {
            return new RetryableException(
              response.status(),
              exception.getMessage(),
              response.request().httpMethod(),
              exception,
              50L, // The retry interval
              response.request());
        }
        return exception;
    }
}

Mind that in this case, we create and return the exception, not throw it.

Finally, we need to plug our decoder in the client builder:

public static <T> T createClient(Class<T> type, String uri) {
    return Feign.builder()
      // ...
      .errorDecoder(new Custom5xxErrorDecoder())
      // ...
}

5. Summary

In this article, we learned how to control the retry logic of the Feign library. We looked into the Retryer interface and how it can be used to manipulate the time and number of retry attempts. Then we created our ErrorDecoder to control which responses warrant retry.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW