1. Introduction

In this tutorial, we’ll look at how we can retry HTTP requests when using Apache HtttpClient. We’ll also explore the default behavior in terms of the library’s retries and ways to configure it.

2. Default Retry Policy

Before we jump into the default behavior, we’ll create a test class with the HttpClient instance and the requests counter:

public class ApacheHttpClientRetryUnitTest {

 private Integer requestCounter;
 private CloseableHttpClient httpClient;

 @BeforeEach
 void setUp() {
 requestCounter = 0;
 }

 @AfterEach
 void tearDown() throws IOException {
 if (httpClient != null) {
 httpClient.close();
 }
 }
}

Let’s start with the default behavior – Apache HttpClient retries at most 3 times all idempotent requests completed with IOException, so we’ll get 4 requests in total. We’ll create here HttpClient that throws IOException for every request, just for the sake of demonstration:

private void createFailingHttpClient() {
 this.httpClient = HttpClientBuilder
 .create()
 .addInterceptorFirst((HttpRequestInterceptor) (request, context) -> requestCounter++)
 .addInterceptorLast((HttpResponseInterceptor) (response, context) -> { throw new IOException(); })
 .build()
}

@Test
public void givenDefaultConfiguration_whenReceviedIOException_thenRetriesPerformed() {
 createFailingHttpClient();
 assertThrows(IOException.class, () -> httpClient.execute(new HttpGet("https://httpstat.us/200")));
 assertThat(requestCounter).isEqualTo(4);
}

There are some IOException subclasses that HttpClient considers non-retryable. More specifically, they are:

• InterruptedIOException
• ConnectException
• UnknownHostException
• SSLException
• NoRouteToHostException

For instance, if we are unable to resolve a DNS name of the target host, then the request won’t be retried:

public void createDefaultApacheHttpClient() {
 this.httpClient = HttpClientBuilder
 .create()
 .addInterceptorFirst((HttpRequestInterceptor) (httpRequest, httpContext) -> {
 requestCounter++;
 }).build();
}

@Test
public void givenDefaultConfiguration_whenDomainNameNotResolved_thenNoRetryApplied() {
 createDefaultApacheHttpClient();
 HttpGet request = new HttpGet(URI.create("http://domain.that.does.not.exist:80/api/v1"));

 assertThrows(UnknownHostException.class, () -> httpClient.execute(request));
 assertThat(requestCounter).isEqualTo(1);
}

As we can notice, these exceptions typically indicate a network or TLS problems. Therefore, they do not relate to unsuccessful HTTP request processing. It means that if the server has responded to our request with 5xx or 4xx, then there will be no retry logic applied:

@Test
public void givenDefaultConfiguration_whenGotInternalServerError_thenNoRetryLogicApplied() throws IOException {
 createDefaultApacheHttpClient();
 HttpGet request = new HttpGet(URI.create("https://httpstat.us/500"));

 CloseableHttpResponse response = assertDoesNotThrow(() -> httpClient.execute(request));
 assertThat(response.getStatusLine().getStatusCode()).isEqualTo(500);
 assertThat(requestCounter).isEqualTo(1);
 response.close();
}

But in most cases, that is not what we want. We typically want to retry on 5xx status codes at least. So, we will need to override the default behavior. We’ll do it in the next section.

3. Idempotency

Before our retries customization, we need to elaborate a bit on the idempotency of requests. It is important since the Apache HTTP client considers all HttpEntityEnclosingRequest implementations non-idempotent. Common implementations of this interface are HttpPost, HttpPut, and HttpPatch classes. So, our PATCH and PUT requests will not be, by default, retried:

@Test
public void givenDefaultConfiguration_whenHttpPatchRequest_thenRetryIsNotApplied() {
 createFailingHttpClient();
 HttpPatch request = new HttpPatch(URI.create("https://httpstat.us/500"));

 assertThrows(IOException.class, () -> httpClient.execute(request));
 assertThat(requestCounter).isEqualTo(1);
}

@Test
public void givenDefaultConfiguration_whenHttpPutRequest_thenRetryIsNotApplied() {
 createFailingHttpClient();
 HttpPut request = new HttpPut(URI.create("https://httpstat.us/500"));

 assertThrows(IOException.class, () -> httpClient.execute(request));
 assertThat(requestCounter).isEqualTo(1);
}

As we can see, there were no retries performed. Even if we received an IOException.

4. Custom RetryHandler

The default behavior we mentioned can be overridden. First, we can set the RetryHandler. For this, there is an option to use DefaultHttpRequestRetryHandler. This is a convenient out-of-the-box implementation of RetryHandler, which by the way, the library uses by default. This default implementation also implements the default behavior we discussed.

By using DefaultHttpRequestRetryHandler, we can set the number of retries we want and whenever HttpClient should retry idempotent requests or not:

private void createHttpClientWithRetryHandler() {
 this.httpClient = HttpClientBuilder
 .create()
 .addInterceptorFirst((HttpRequestInterceptor) (httpRequest, httpContext) -> requestCounter++)
 .addInterceptorLast((HttpResponseInterceptor) (httpRequest, httpContext) -> { throw new IOException(); })
 .setRetryHandler(new DefaultHttpRequestRetryHandler(6, true))
 .build();
}

@Test
public void givenConfiguredRetryHandler_whenHttpPostRequest_thenRetriesPerformed() {
 createHttpClientWithRetryHandler();

 HttpPost request = new HttpPost(URI.create("https://httpstat.us/500"));

 assertThrows(IOException.class, () -> httpClient.execute(request));
 assertThat(requestCounter).isEqualTo(7);
}

As we can see, we configured the DefaultHttpRequestRetryHandler to make 6 retries. See the first constructor parameter. Also, we enabled the retry of idempotent requests. See the second constructor boolean parameter. Therefore, HttpCleint executes our POST request 7 times – 1 original request and 6 retries.

Also, if this level of customization is not enough, we can create our own RetryHandler:

private void createHttpClientWithCustomRetryHandler() {
 this.httpClient = HttpClientBuilder
 .create()
 .addInterceptorFirst((HttpRequestInterceptor) (httpRequest, httpContext) -> requestCounter++)
 .addInterceptorLast((HttpResponseInterceptor) (httpRequest, httpContext) -> { throw new IOException(); })
 .setRetryHandler((exception, executionCount, context) -> {
 if (executionCount <= 4 && Objects.equals("GET", ((HttpClientContext) context).getRequest().getRequestLine().getMethod())) {
 return true;
 } else {
 return false;
 }
 }).build();
}

@Test
public void givenCustomRetryHandler_whenUnknownHostException_thenRetryAnyway() {
 createHttpClientWithCustomRetryHandler();

 HttpGet request = new HttpGet(URI.create("https://domain.that.does.not.exist/200"));

 assertThrows(IOException.class, () -> httpClient.execute(request));
 assertThat(requestCounter).isEqualTo(5);
}

Here we basically said – to retry all GET requests 4 times regardless of the exception that occurred. So in the example above, we have retried UnknownHostException.

5. Disabling Retry Logic

Finally, there are cases when we would want to disable the reties. We can provide a RetryHandler that just always returns false, or we can use disableAutomaticRetries():

private void createHttpClientWithRetriesDisabled() {
 this.httpClient = HttpClientBuilder
 .create()
 .addInterceptorFirst((HttpRequestInterceptor) (httpRequest, httpContext) -> requestCounter++)
 .addInterceptorLast((HttpResponseInterceptor) (httpRequest, httpContext) -> { throw new IOException(); })
 .disableAutomaticRetries()
 .build();
}

@Test
public void givenDisabledRetries_whenExecutedHttpRequestEndUpWithIOException_thenRetryIsNotApplied() {
 createHttpClientWithRetriesDisabled();
 HttpGet request = new HttpGet(URI.create("https://httpstat.us/200"));

 assertThrows(IOException.class, () -> httpClient.execute(request));
 assertThat(requestCounter).isEqualTo(1);
}

By calling disableAutomaticRetries() on the HttpClientBuilder, we disabled all retries in the HttpClient. That means that no requests will be retired.

6. Conclusion

In this tutorial, we have discussed the default retry behavior in Apache HttpClient. Out-of-the-box RetryHandler will retry idempotent requests 3 times, considering the exception occurred. However, we can configure the number of retries and the non-idempotent requests retry policy. Also, we can provide our own RetryHandler implementation for even further customization. Finally, we can disable the retires by calling a method on HttpClientBuilder during HttpClient construction.