Class RetryPolicy

java.lang.Object
com.eqixiac.equinix.core.http.RetryPolicy
public final class RetryPolicy extends Object
Controls automatic retry of transient failures. By default the SDK retries throttling (429) and the common transient server errors (500, 502, 503, 504) as well as transient IOExceptions, using exponential backoff with full jitter and honoring a Retry-After header when present.

To avoid duplicate side effects, retries of 5xx responses and IOExceptions are by default applied only to idempotent methods - everything except POST and PATCH (RFC 5789: PATCH is not idempotent in general, and the SDK sends RFC 6902 documents whose add operations would apply twice). A transient failure that occurs after the server has already processed a POST create or a PATCH would otherwise re-send it and duplicate the side effect. Set retryNonIdempotentMethods if your endpoints are safe to retry (e.g. they dedupe via an idempotency key, or the POST is a side-effect-free search).

A 429 response is exempt from the idempotency gate: it means the server explicitly did not process the request, so re-sending is always safe - 429s are retried for every method (honoring Retry-After) as long as 429 is in the retryable status set.

Retries are bounded by getMaxRetries() attempts beyond the initial request. Pass none() to disable retries entirely, or build a custom policy via the constructor.

Author:
ianjones

  • Constructor Summary

    Constructors
    Constructor
    Description
    RetryPolicy(int maxRetries, long baseDelayMillis, long maxDelayMillis, Set<Integer> retryableStatusCodes, boolean retryOnIoException, boolean honorRetryAfter)
    Constructor for RetryPolicy that retries only idempotent methods (POST and PATCH are never retried).
    RetryPolicy(int maxRetries, long baseDelayMillis, long maxDelayMillis, Set<Integer> retryableStatusCodes, boolean retryOnIoException, boolean honorRetryAfter, boolean retryNonIdempotentMethods)
    Full constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    computeBackoffMillis(int attempt, Long retryAfterMillis)
    Computes the backoff wait before the given retry attempt.
    static RetryPolicy
    defaultPolicy()
    The default policy: up to 3 retries on 429/500/502/503/504 and transient IO errors, 500ms base backoff capped at 20s, with Retry-After honored.
    int
    getMaxRetries()
     
    boolean
    isRetryable(int statusCode, HttpMethod method)
    Whether a response with the given status code should be retried for a request with the given method.
    boolean
    isRetryableMethod(HttpMethod method)
    Whether a request with the given HTTP method is eligible for retry of a failure that may have had server-side effects (a 5xx response or a transport IOException).
    boolean
    isRetryableStatus(int statusCode)
    Whether a response with the given status code should be retried.
    boolean
    isRetryOnIoException()
    Whether transient IO exceptions are retried.
    static RetryPolicy
    none()
    A policy that performs no retries.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RetryPolicy

      public RetryPolicy(int maxRetries, long baseDelayMillis, long maxDelayMillis, Set<Integer> retryableStatusCodes, boolean retryOnIoException, boolean honorRetryAfter)
      Constructor for RetryPolicy that retries only idempotent methods (POST and PATCH are never retried).
      Parameters:
      maxRetries - maximum retry attempts beyond the initial request (0 disables retries)
      baseDelayMillis - base backoff delay; the n-th retry waits up to base * 2^n
      maxDelayMillis - ceiling on any single backoff wait
      retryableStatusCodes - HTTP status codes that trigger a retry
      retryOnIoException - whether transient IOExceptions are retried
      honorRetryAfter - whether a Retry-After response header overrides the computed backoff

    • RetryPolicy

      public RetryPolicy(int maxRetries, long baseDelayMillis, long maxDelayMillis, Set<Integer> retryableStatusCodes, boolean retryOnIoException, boolean honorRetryAfter, boolean retryNonIdempotentMethods)
      Full constructor. Also reachable fluently via builder() - preferable when configuring by hand, since the positional form lines up two long delays and three boolean flags that are easy to transpose silently: RetryPolicy.builder().maxRetries(5).baseDelayMillis(200).retryableStatusCodes(Set.of(429)).build(). Note the builder applies no defaults beyond Java's zero-values; an unset retryableStatusCodes is treated as an empty set (no status-triggered retries).
      Parameters:
      maxRetries - maximum retry attempts beyond the initial request (0 disables retries)
      baseDelayMillis - base backoff delay; the n-th retry waits up to base * 2^n
      maxDelayMillis - ceiling on any single backoff wait
      retryableStatusCodes - HTTP status codes that trigger a retry
      retryOnIoException - whether transient IOExceptions are retried
      honorRetryAfter - whether a Retry-After response header overrides the computed backoff
      retryNonIdempotentMethods - whether non-idempotent methods (POST, PATCH) are also retried - leave false unless your endpoints dedupe retried requests

  • Method Details

    • isRetryableMethod

      public boolean isRetryableMethod(HttpMethod method)
      Whether a request with the given HTTP method is eligible for retry of a failure that may have had server-side effects (a 5xx response or a transport IOException). POST and PATCH are treated as non-idempotent (per RFC 5789 a PATCH - such as the SDK's RFC 6902 add operations - may not be safely re-applied) and are not retried unless retryNonIdempotentMethods is set. This gate does not apply to 429 responses - see isRetryable(int, HttpMethod).
      Parameters:
      method - the request method (may be null, treated as retryable)
      Returns:
      true if retries are permitted for this method

    • isRetryable

      public boolean isRetryable(int statusCode, HttpMethod method)
      Whether a response with the given status code should be retried for a request with the given method. A 429 (Too Many Requests) means the server explicitly did not process the request, so re-sending it can never duplicate a side effect - 429 is retryable for every method (including POST and PATCH), provided 429 is in the retryable status set. All other retryable statuses (the 5xx family) remain gated on isRetryableMethod(HttpMethod).
      Parameters:
      statusCode - the HTTP status code of the failed attempt
      method - the request method (may be null, treated as retryable)
      Returns:
      true if a retry is permitted

    • defaultPolicy

      public static RetryPolicy defaultPolicy()
      The default policy: up to 3 retries on 429/500/502/503/504 and transient IO errors, 500ms base backoff capped at 20s, with Retry-After honored.
      Returns:
      the default policy

    • none

      public static RetryPolicy none()
      A policy that performs no retries.
      Returns:
      a no-retry policy

    • getMaxRetries

      public int getMaxRetries()
      Returns:
      the maximum number of retries

    • isRetryableStatus

      public boolean isRetryableStatus(int statusCode)
      Whether a response with the given status code should be retried.
      Parameters:
      statusCode - the HTTP status code
      Returns:
      true if retryable

    • isRetryOnIoException

      public boolean isRetryOnIoException()

      Whether transient IO exceptions are retried.

      Returns:
      true if IO exceptions are retried

    • computeBackoffMillis

      public long computeBackoffMillis(int attempt, Long retryAfterMillis)
      Computes the backoff wait before the given retry attempt.
      Parameters:
      attempt - zero-based retry attempt index
      retryAfterMillis - the server-provided Retry-After in millis, or null
      Returns:
      the number of milliseconds to wait