Retrying RestTemplate HTTP Requests in Java When the Host Is Offline

1. Overview

When an HTTP request fails because the host is temporarily offline or unreachable, it’s often more reliable to retry the request rather than fail immediately. This technique known as retry logic, helps improve the resilience and reliability of our applications, especially when dealing with unstable networks or remote services.

In Java, the Spring Framework’s RestTemplate is a widely used client for making RESTful calls. However, by default the RestTemplate doesn’t automatically retry requests on failures such as SocketTimeoutException or UnknownHostException.

In this tutorial, we’ll explore how to implement automatic retries for RestTemplate requests in a clean and reusable way. We’ll use Spring Boot for simplicity. The goal is to create a small retry mechanism that automatically reattempts HTTP requests when the host is offline or temporarily unavailable.

2. Understand the Problem

When a host is offline or unreachable, RestTemplate typically throws a ResourceAccessException. This exception wraps lower-level exceptions, such as ConnectException or UnknownHostException. Without retry logic, our application would fail immediately on the first attempt.

Let’s first understand what happens when we try to connect to an offline host:

RestTemplate restTemplate = new RestTemplate();
String url = "http://localhost:8090/api/data";

try {
    String response = restTemplate.getForObject(url, String.class);
} catch (ResourceAccessException e) {
    // This will be thrown when host is offline
    System.out.println("Host is unreachable: " + e.getMessage());
}

The above code will fail immediately if the host at port 8090 is not running. To make our application more resilient, we need to implement retry logic.

3. Manual Retry Implementation

The most straightforward approach is to implement retry logic manually using a loop. This gives us complete control over the retry behavior, including the number of attempts and the delay between retries.

Before we dive into building custom retry mechanisms, it’s essential to set up a robust and reusable HTTP client that our retry logic will rely on. In most Spring Boot applications, this is handled through a RestTemplate bean. By configuring it properly, we can control connection behavior such as timeouts and request handling even before retry logic comes into play.

The following configuration class defines a RestTemplate bean that serves as the foundation for making reliable REST calls throughout the application:

public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate() {
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory();
        factory.setConnectTimeout(5000);
        factory.setConnectionRequestTimeout(5000);

        return new RestTemplate(factory);
    }
}

3.1. Basic Retry Logic

Before we bring in any frameworks, let’s first understand how a simple retry mechanism works using plain Java. Here’s a straightforward implementation that retries a fixed number of times with a delay between attempts:

public class RestTemplateRetryService {

    private RestTemplate restTemplate = new RestTemplate();
    private int maxRetries = 3;
    private long retryDelay = 2000;

    public String makeRequestWithRetry(String url) {
        int attempt = 0;
        while (attempt < maxRetries) {
            try {
                return restTemplate.getForObject(url, String.class);
            } catch (ResourceAccessException e) {
                attempt++;
                if (attempt >= maxRetries) {
                    throw new RuntimeException("Failed after " + maxRetries + " attempts", e);
                }
                try {
                    Thread.sleep(retryDelay);
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("Retry interrupted", ie);
                }
            }
        }
        throw new RuntimeException("Unexpected error in retry logic");
    }
}

This implementation attempts the request up to three times, waiting two seconds between each attempt. If all attempts fail, it throws a RuntimeException with the original cause for easier debugging.

3.2. Testing the Retry Logic

We can test this behavior by simulating an offline host scenario. Now, let’s verify that the retry mechanism actually triggers multiple attempts when the host is offline.

The following JUnit test checks both exception handling and the expected delay:

@Test
void whenHostOffline_thenRetriesAndFails() {
    RestTemplateRetryService service = new RestTemplateRetryService();
    String offlineUrl = "http://localhost:9999/api/data";
    
    long startTime = System.currentTimeMillis();
    
    assertThrows(RuntimeException.class, () -> {
        service.makeRequestWithRetry(offlineUrl);
    });
    
    long duration = System.currentTimeMillis() - startTime;
    assertTrue(duration >= 4000); // Should take at least 4 seconds (2 retries * 2 seconds)
}

This test verifies that the retry mechanism is functioning correctly by ensuring that the total execution time is at least four seconds, indicating that retries occurred with the expected delays.

3.3. Exponential Backoff Strategy

For production systems, exponential backoff is often preferable as it reduces load on the failing service. In real-world systems, using a fixed retry delay can sometimes put unnecessary pressure on another service. A better approach is to use exponential backoff, where the wait time increases after each failure.

This allows the system to recover more gracefully and avoids overwhelming the target service:

@Service
public class ExponentialBackoffRetryService {

    private final RestTemplate restTemplate;
    private int maxRetries = 5;
    private long initialDelay = 1000;

    public ExponentialBackoffRetryService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    public String makeRequestWithExponentialBackoff(String url) {
        int attempt = 0;
        while (attempt < maxRetries) {
            try {
                return restTemplate.getForObject(url, String.class);
            } catch (ResourceAccessException e) {
                attempt++;
                if (attempt >= maxRetries) {
                    throw new RuntimeException("Failed after " + maxRetries + " attempts", e);
                }
                long delay = initialDelay * (long) Math.pow(2, attempt - 1);
                try {
                    Thread.sleep(delay);
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("Retry interrupted", ie);
                }
            }
        }
        throw new RuntimeException("Unexpected error in retry logic");
    }

    public void setMaxRetries(int maxRetries) {
        this.maxRetries = maxRetries;
    }

    public void setInitialDelay(long initialDelay) {
        this.initialDelay = initialDelay;
    }
}

With exponential backoff, the delay is dynamically doubled after each failed attempt, starting with one second, then two, four, eight, and so on. By increasing the wait time progressively, it eases the retry pressure on the remote service, giving it time to recover before the next request.

3.4. Testing Retry with Exponential Backoff

To validate that the exponential backoff logic behaves correctly, we can measure the total execution time when the host is unreachable. The test below ensures that retries occur with increasing delays before ultimately failing:

@Test
void whenHostOffline_thenRetriesWithExponentialBackoff() {
    service.setMaxRetries(4);
    service.setInitialDelay(500);

    String offlineUrl = "http://localhost:9999/api/data";
    long startTime = System.currentTimeMillis();

    assertThrows(RuntimeException.class, () -> {
        service.makeRequestWithExponentialBackoff(offlineUrl);
    });

    long duration = System.currentTimeMillis() - startTime;
    assertTrue(duration >= 3500);
}

This test verifies that the exponential backoff delay is applied correctly by checking the total time taken. Since each retry waits progressively longer, the duration exceeding 3.5 seconds confirms that multiple retries and increasing wait intervals occurred as expected.

4. Using Spring Retry

Spring Retry simplifies retrying by eliminating the need for manual loops, counters, and delays. Instead of writing retry logic ourselves, we can declaratively apply retry behavior to any method. This keeps the code cleaner, easier to maintain, and far more testable. Before using these features, we need a small amount of setup in our project.

4.1. Adding Dependencies and Enabling Retry

Before we can use it, we need to include the required dependencies (spring-retry and spring-aspects) in our pom.xml:

<dependency>
    <groupId>org.springframework.retry</groupId>
    <artifactId>spring-retry</artifactId>
    <version>2.0.12</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aspects</artifactId>
    <version>7.0.0</version>
</dependency>

Once the dependencies are added, the next step is to enable retry functionality inside our Spring Boot application. We do this using the @EnableRetry annotation, which tells Spring to intercept method calls and automatically apply retry rules. This will be added to the existing configuration in the RestTemplateConfig class:

@EnableRetry
public class RestTemplateConfig {
    // ...
}

This setup eliminates the need for manual retry loops, making the retry logic cleaner, more declarative, and easier to maintain across large applications.

4.2. Declarative Retry with Annotations

After enabling retry support, we can now use the @Retryable annotation to mark specific methods that should automatically retry when certain exceptions occur. This approach is ideal for service calls where transient network issues or host unavailability might cause intermittent failures:

@Service
public class RestClientService {

    private final RestTemplate restTemplate;

    public RestClientService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    @Retryable(
      retryFor = {ResourceAccessException.class},
      maxAttempts = 3,
      backoff = @Backoff(delay = 2000))
    public String fetchData(String url) {
        return restTemplate.getForObject(url, String.class);
    }

    @Recover
    public String recover(ResourceAccessException e, String url) {
        return "Fallback response after all retries failed for: " + url;
    }
}

This declarative retry approach simplifies code significantly, removing the need for custom retry loops or thread sleeps. It’s beneficial for microservices or APIs that depend on external systems, where temporary outages are common.

4.3. Testing Spring Retry

Once the @Retryable logic is in place, it’s important to confirm that it behaves as expected when real network issues occur. In this case, we’ll simulate a scenario where the host is offline and verify that our service retries the configured number of times before falling back to a recovery method:

@SpringBootTest
class RestClientServiceTest {

    @Autowired
    private RestClientService restClientService;

    @Test
    void whenHostOffline_thenRetriesAndRecovers() {
        String offlineUrl = "http://localhost:9999/api/data";
        
        String result = restClientService.fetchData(offlineUrl);
        
        assertTrue(result.contains("Fallback response"));
        assertTrue(result.contains(offlineUrl));
    }
}

This test verifies that when the host is offline, the service retries as configured and eventually calls the recovery method, returning the fallback response.

4.4. Programmatic Configuration

While annotations like @Retryable are convenient, some situations require finer control, especially when different components require unique retry strategies or when retry settings need to be dynamically adjusted. In such cases, we can configure retry behavior programmatically using RetryTemplate:

@Configuration
public class RetryTemplateConfig {

    @Bean
    public RetryTemplate retryTemplate() {
        RetryTemplate retryTemplate = new RetryTemplate();

        FixedBackOffPolicy backOffPolicy = new FixedBackOffPolicy();
        backOffPolicy.setBackOffPeriod(2000);

        SimpleRetryPolicy retryPolicy = new SimpleRetryPolicy();
        retryPolicy.setMaxAttempts(3);

        retryTemplate.setBackOffPolicy(backOffPolicy);
        retryTemplate.setRetryPolicy(retryPolicy);

        return retryTemplate;
    }
}

This explicit configuration allows us to centralize retry logic in one place and reuse it across multiple services. Next, we can inject RestTemplate and the above RetryTemplate into the RetryTemplateService service class to handle transient failures gracefully:

@Service
public class RetryTemplateService {

    private RestTemplate restTemplate;
    private RetryTemplate retryTemplate;

    public RetryTemplateService(RestTemplate restTemplate, RetryTemplate retryTemplate) {
        this.restTemplate = restTemplate;
        this.retryTemplate = retryTemplate;
    }

    public String fetchDataWithRetryTemplate(String url) {
        return retryTemplate.execute(context -> {
            return restTemplate.getForObject(url, String.class);
        }, context -> {
            return "Fallback response";
        });
    }
}

This approach provides more flexibility than annotations, making it ideal when retry logic needs to be constructed dynamically or applied conditionally at runtime. For instance, we could adjust retry counts or delays based on API types or environment profiles.

4.5. Testing Programmatic Configuration

Now, let’s test that our RetryTemplate configuration actually performs retries and triggers the fallback logic when the target service is unavailable:

@Test
void whenHostOffline_thenReturnsFallback() {
    String offlineUrl = "http://localhost:9999/api/data";

    long startTime = System.currentTimeMillis();
    String result = retryTemplateService.fetchDataWithRetryTemplate(offlineUrl);
    long duration = System.currentTimeMillis() - startTime;

    assertEquals("Fallback response", result);
    assertTrue(duration >= 4000);
}

In this test, the offline URL ensures that all retry attempts will fail, forcing RetryTemplate to move through all three configured retries before invoking the fallback block.

5. Conclusion

In this article, we explored multiple approaches to retry RestTemplate HTTP requests when the host is offline. We examined manual retry implementations with both fixed and exponential backoff strategies, as well as declarative retry with Spring Retry.

Each approach has its merit, like manual implementation provides maximum control, and Spring Retry offers simplicity and ease of use. The choice depends on our application’s specific requirements and complexity.

Properly implemented retry logic significantly improves application resilience in distributed systems. Combined with appropriate timeouts and fallback mechanisms, these patterns help create robust applications that gracefully handle temporary network failures and service unavailability.

As always, the code for these examples is available over on GitHub.