Retries with Exponential Backoff

APIMatic's SDKs provides retries with Exponential Backoff. It's a robust mechanism designed to handle transient failures when interacting with APIs. Transient failures, such as server overloads or temporary connectivity issues, are brief and irregular but can disrupt the communication between applications and APIs. This feature ensures that API requests are retried intelligently by gradually increasing the wait time between retries, thereby improving reliability without overwhelming the server. It addresses common issues like timeouts (HTTP 408), server errors (5XX), and rate-limiting (HTTP 429) scenarios.

Key Benefits

• Enhanced Reliability: Automatically recovers from transient failures, reducing the likelihood of dropped requests.
• Server-Friendly Behavior: Exponential backoff prevents overloading the server by spacing out retry attempts progressively.
• Configurable Retry Logic: Offers flexibility to define the number of retries, wait intervals, and maximum retry duration based on application requirements.

How to Configure it in APIMatic's SDKs

To enable retries with exponential backoff in your SDK configuration, follow these steps:

1. Define Retry Conditions:
   • Configure HTTP methods to retry (for example, GET and PUT).
   • Specify the HTTP status codes or exceptions that should trigger a retry, such as 408 (Request Timeout) HTTP Status code.

note

You can force retries for an endpoint, regardless of its idempotency, by setting forceRetries to true within the x-operation-settings endpoint extension in the OpenAPI specification file. For more details, refer to the documentation.

2. Set Retry Limits:

   • Configure the number of retries (for example, 3 retries).
   • Optionally, set a maximum retry wait time to prevent indefinite retry loops (for example, 200 seconds).

3. Set Retry Timeout and Intervals:

   • Configure the timeout, which is the time interval the application waits for a response before declaring the call a failure (for example, 6 seconds).
   • Configure the retry interval, which is the time interval between API calls (for example, 2 seconds).

4. Enable Exponential Backoff:

   • Define a backoff factor (for example, 2) which specifies the factor to increase interval between retries.

5. Integrate Retry Logic: Apply the configuration during SDK initialization.

TypeScript

const client = new Client({
  ...
  httpClientOptions: { // sets the http client confiuration
    timeout: 6, // sets the timeout
    retryConfig: {
      httpMethodsToRetry: ["GET", "PUT"], // sets the http methods to retry
      httpStatusCodesToRetry: [408], // sets the http status code to retry
      maxNumberOfRetries: 3, // sets number of retries
      maximumRetryWaitTime: 200, // sets maximum retry wait time interval
      retryInterval: 2, // sets retry interval before declaring the call a failure
      backoffFactor: 2, // sets back off factor to 2
    },
  },
});

Java

Client client = new Client.Builder()
  ...
  .httpClientConfig(configBuilder -> configBuilder // sets the http client confiuration
    .httpMethodsToRetry(new HashSet<>(Arrays.asList(HttpMethod.GET, HttpMethod.PUT))) // sets the http methods to retry
    .httpStatusCodesToRetry(new HashSet<>(408)) // sets the http status code to retry
    .numberOfRetries(3) // sets number of retries
    .maximumRetryWaitTime(200) // sets maximum retry wait time interval
    .timeout(6) // sets the timeout
    .retryInterval(2) // sets retry interval before declaring the call a failure
    .backOffFactor(2) // sets back off factor to 2
  )
  .build();

Python

client = Client(
  ...
  retry_methods=['GET', 'PUT'], # sets the http methods to retry
  retry_statuses=[408], # sets the http status code to retry
  max_retries=3, # sets number of retries
  timeout=6, # sets the timeout
  backoff_factor=2 # sets back off factor to 2
)

.NET

note

To enable retries with backoff in the .NET SDK, you need to enable the UserConfigurableRetries CodeGen setting. For additional information about CodeGen settings, refer to the CodeGen Settings Overview.

This feature accepts a Boolean value and is disabled by default (false).

"info": {
    ...,
    "x-codegen-settings": {
        "UserConfigurableRetries": "true"
    }
}

var client = new Client.Builder()
  ...
  .HttpClientConfig(config => config // sets the http client confiuration
    .RequestMethodsToRetry([HttpMethod.Get, HttpMethod.Put]) // sets the http methods to retry
    .StatusCodesToRetry([408]) // sets the http status code to retry
    .NumberOfRetries(3) // sets number of retries
    .MaximumRetryWaitTime(TimeSpan.FromSeconds(200)) // sets maximum retry wait time interval
    .Timeout(TimeSpan.FromSeconds(6)) // sets the timeout
    .RetryInterval(2) // sets retry interval before declaring the call a failure
    .BackoffFactor(2) // sets back off factor to 2
    .Build()
  )
  .Build();

Go

client := api.NewClient(
        ...
        api.CreateConfiguration(
            api.WithHttpConfiguration(
                api.CreateHttpConfiguration(
                    api.WithTimeout(6), // sets the timeout
                    api.WithRetryConfiguration(api.NewRetryConfiguration(
                        api.WithRetryOnTimeout(true), // enable retries
                        api.WithHttpMethodsToRetry([]string{"GET", "PUT"}), // sets the http methods to retry
                        api.WithHttpStatusCodesToRetry([]int64{408}), // sets the http status code to retry
                        api.WithMaxRetryAttempts(3), // sets number of retries
                        api.WithMaximumRetryWaitTime(200), // sets maximum retry wait time interval
                        api.WithRetryInterval(2), // sets retry interval before declaring the call a failure
                        api.WithBackoffFactor(2), // sets back off factor to 2
                    )),
                ),
            ),
        ),
    )

PHP

$client = TesterClientBuilder::init()
  ...
  ->enableRetries(true) // enable retries
  ->httpMethodsToRetry(['GET', 'PUT']) // sets the http methods to retry
  ->httpStatusCodesToRetry([408]) // sets the http status code to retry
  ->numberOfRetries(3) // sets number of retries
  ->maximumRetryWaitTime(200) // sets maximum retry wait time interval
  ->timeout(6) // sets the timeout
  ->retryInterval(2) // sets retry interval before declaring the call a failure
  ->backOffFactor(2) // sets back off factor to 2
  ->build();

Ruby

client = API::Client.new(
  ...
  retry_methods: %i[get put], # sets the http methods to retry
  retry_statuses: [408], # sets the http status code to retry
  max_retries: 3, # sets number of retries
  timeout: 6, # sets the timeout
  retry_interval: 2, # sets retry interval before declaring the call a failure
  backoff_factor: 2, # sets back off factor to 2
)

tip

Default values of Timeout and Retries can be configured via Timeout and Retries CodeGen settings.

Use Cases

• Handling Temporary Server Downtime: Automatically retry requests during brief outages until the service recovers.
• Dealing with Rate Limiting: Adheres to Retry-After headers in HTTP 429 responses to avoid unnecessary retries.
• Managing Network Fluctuations: Retries requests during temporary connectivity issues, improving reliability in unstable network environments.
• Batch Processing: Ensures large data operations aren't interrupted by transient failures.

Limitations

• Non-Idempotent Methods: Retrying non-idempotent HTTP methods like POST may result in unintended side effects (for example, duplicate resource creation).
• Maximum Wait Time: Exponential backoff can lead to longer delays in some scenarios, potentially impacting time-sensitive operations.