Implementation:Apache Paimon ExponentialHttpRequestRetryStrategy

Knowledge Sources	Apache_Paimon
Domains	REST API, HTTP Client, Resilience
Last Updated	2026-02-08 00:00 GMT

Overview

ExponentialHttpRequestRetryStrategy implements an exponential backoff retry strategy for HTTP requests with configurable retry limits and intelligent failure detection.

Description

This class implements Apache HttpClient's HttpRequestRetryStrategy interface to provide intelligent retry logic for failed HTTP requests. It uses an exponential backoff algorithm to progressively increase wait times between retry attempts, helping to avoid overwhelming servers during temporary outages or rate limiting scenarios.

The strategy distinguishes between retriable and non-retriable failures. It will retry requests that receive HTTP 429 (Too Many Requests) or 503 (Service Unavailable) status codes, as these typically indicate temporary server-side issues. However, it will not retry requests that encounter certain exceptions like InterruptedIOException, UnknownHostException, ConnectException, or SSLException, as these typically indicate problems that won't be resolved by retrying.

The retry interval calculation respects server-provided Retry-After headers when present, and falls back to an exponential backoff formula with jitter when not specified. The exponential backoff doubles the wait time with each retry (capped at 64 seconds), and adds random jitter to prevent thundering herd problems where multiple clients retry simultaneously.

Usage

Use ExponentialHttpRequestRetryStrategy when configuring HTTP clients for REST catalog operations that need resilient communication with potentially unreliable or rate-limited servers. This strategy is particularly useful for production environments where transient network issues or server load spikes should not cause immediate failures.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/rest/ExponentialHttpRequestRetryStrategy.java

Signature

class ExponentialHttpRequestRetryStrategy implements HttpRequestRetryStrategy {
    private final int maxRetries;
    private final Set<Class<? extends IOException>> nonRetriableExceptions;
    private final Set<Integer> retriableCodes;

    ExponentialHttpRequestRetryStrategy(int maximumRetries) {
        // Constructor validates maximumRetries > 0
        // Initializes retriableCodes with 429 and 503
        // Initializes nonRetriableExceptions with network-related exceptions
    }

    @Override
    public boolean retryRequest(
            HttpRequest request, IOException exception, int execCount, HttpContext context);

    @Override
    public boolean retryRequest(HttpResponse response, int execCount, HttpContext context);

    @Override
    public TimeValue getRetryInterval(HttpResponse response, int execCount, HttpContext context);
}

Import

import org.apache.paimon.rest.ExponentialHttpRequestRetryStrategy;

I/O Contract

Inputs

Name	Type	Required	Description
maximumRetries	int	Yes	Maximum number of retry attempts (must be > 0)
request	HttpRequest	Yes	The HTTP request being executed
exception	IOException	Yes	Exception thrown during request execution
response	HttpResponse	Yes	HTTP response received from server
execCount	int	Yes	Number of times the request has been executed
context	HttpContext	Yes	HTTP execution context

Outputs

Name	Type	Description
retryRequest()	boolean	Returns true if the request should be retried, false otherwise
getRetryInterval()	TimeValue	Returns the time to wait before the next retry attempt

Usage Examples

import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.paimon.rest.ExponentialHttpRequestRetryStrategy;

// Create a retry strategy with maximum 5 retries
ExponentialHttpRequestRetryStrategy retryStrategy =
    new ExponentialHttpRequestRetryStrategy(5);

// Configure HTTP client with the retry strategy
CloseableHttpClient httpClient = HttpClients.custom()
    .setRetryStrategy(retryStrategy)
    .build();

// The retry strategy will automatically:
// 1. Retry on HTTP 429 (Too Many Requests) and 503 (Service Unavailable)
// 2. Respect server's Retry-After header if present
// 3. Use exponential backoff with jitter:
//    - 1st retry: ~1 second
//    - 2nd retry: ~2 seconds
//    - 3rd retry: ~4 seconds
//    - 4th retry: ~8 seconds
//    - 5th retry: ~16 seconds

// Example: Making a request with automatic retries
try {
    HttpGet request = new HttpGet("https://catalog.example.com/api/tables");
    CloseableHttpResponse response = httpClient.execute(request);
    // Process response
} catch (IOException e) {
    // Non-retriable exception or max retries exceeded
    System.err.println("Request failed after retries: " + e.getMessage());
}

// The strategy will NOT retry these exceptions:
// - InterruptedIOException (request was cancelled)
// - UnknownHostException (DNS resolution failed)
// - ConnectException (connection refused)
// - SSLException (SSL/TLS error)
// - NoRouteToHostException (network unreachable)
// - ConnectionClosedException (connection closed unexpectedly)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment