Package com.guinetik.rr.interceptor

Class RetryInterceptor

  • All Implemented Interfaces:
    RequestInterceptor
    public class RetryInterceptor
extends Object
implements RequestInterceptor
    Interceptor that retries failed requests with configurable backoff.

    This interceptor catches exceptions during request execution and retries them based on configurable criteria. It supports exponential backoff, maximum retry limits, and custom retry predicates.

    Default Retry Behavior

    By default, retries are attempted for:

    • 5xx Server Errors (500-599)
    • 408 Request Timeout
    • 429 Too Many Requests
    • Network/Connection errors (status code 0 or -1)

    The following are NOT retried:

    Basic Usage

    
 // Retry up to 3 times with 1 second initial delay
 RetryInterceptor retry = new RetryInterceptor(3, 1000);

 RocketClient client = RocketClientFactory.builder("https://api.example.com")
     .withInterceptor(retry)
     .build();

    Exponential Backoff

    
 // Retry with exponential backoff: 1s, 2s, 4s
 RetryInterceptor retry = new RetryInterceptor(3, 1000, 2.0);

    Custom Retry Predicate

    
 // Only retry on specific status codes
 RetryInterceptor retry = RetryInterceptor.builder()
     .maxRetries(3)
     .initialDelayMs(500)
     .retryOn(e -> e.getStatusCode() == 503)
     .build();
    Since:
    1.1.0
    Author:
    guinetik <guinetik@gmail.com>
    See Also:
    RequestInterceptor, InterceptorChain

    • Constructor Detail

      • RetryInterceptor

        public RetryInterceptor()
        Creates a retry interceptor with default settings. Uses 3 retries, 1 second initial delay, 2x backoff, 30 second max delay.

      • RetryInterceptor

        public RetryInterceptor​(int maxRetries,
                        long initialDelayMs)
        Creates a retry interceptor with custom retry count and delay.
        Parameters:
        maxRetries - Maximum number of retries (must be positive)
        initialDelayMs - Initial delay between retries in milliseconds

      • RetryInterceptor

        public RetryInterceptor​(int maxRetries,
                        long initialDelayMs,
                        double backoffMultiplier)
        Creates a retry interceptor with exponential backoff.
        Parameters:
        maxRetries - Maximum number of retries
        initialDelayMs - Initial delay in milliseconds
        backoffMultiplier - Multiplier for each subsequent retry (e.g., 2.0 for doubling)

      • RetryInterceptor

        public RetryInterceptor​(int maxRetries,
                        long initialDelayMs,
                        double backoffMultiplier,
                        long maxDelayMs,
                        Predicate<RocketRestException> retryPredicate)
        Creates a fully customized retry interceptor.
        Parameters:
        maxRetries - Maximum number of retries
        initialDelayMs - Initial delay in milliseconds
        backoffMultiplier - Multiplier for exponential backoff
        maxDelayMs - Maximum delay cap in milliseconds
        retryPredicate - Custom predicate to determine if exception is retryable (null for default)

    • Method Detail

      • onError

        public <Req,​Res> Res onError​(RocketRestException e,
                                   RequestSpec<Req,​Res> request,
                                   InterceptorChain chain)
                            throws RocketRestException
        Description copied from interface: RequestInterceptor
        Called when an exception occurs during request execution.

        This method can:

        • Retry the request using InterceptorChain.retry(RequestSpec)
        • Transform the exception into a different one
        • Recover and return a fallback response
        • Rethrow the exception (default behavior)
        Specified by:
        onError in interface RequestInterceptor
        Type Parameters:
        Req - The request body type
        Res - The response type
        Parameters:
        e - The exception that occurred
        request - The request that failed
        chain - The interceptor chain (use for retry)
        Returns:
        A recovered response, or throws an exception
        Throws:
        RocketRestException - If the error cannot be handled

      • getOrder

        public int getOrder()
        Description copied from interface: RequestInterceptor
        Returns the order of this interceptor in the chain.

        Lower values execute first. Use negative values for interceptors that must run early (e.g., authentication), and positive values for interceptors that should run late (e.g., logging).

        Suggested ordering:

        • -100: Authentication/Authorization
        • 0: Default (most interceptors)
        • 100: Retry logic
        • 200: Logging/Metrics
        Specified by:
        getOrder in interface RequestInterceptor
        Returns:
        The order value (lower = earlier)

      • builder

        public static RetryInterceptor.Builder builder()
        Creates a builder for custom retry configuration.
        Returns:
        A new builder instance