Speakeasy Logo
Skip to Content
DocumentationCustomizeSDK BehaviorEnable Retries

Retries

With Speakeasy, generate SDKs that automatically retry requests that fail due to network errors or any configured HTTP status code. Enable retries globally for all requests or on a per-request basis by using the x-speakeasy-retries extension in the OpenAPI document. The SDK end user can then override the default configuration by passing in a RetryConfig object to the operation at runtime.

Global Retries

If you add the x-speakeasy-retries extension to the root of the OpenAPI document, the SDK Generator will generate a global retry configuration that will be used for all requests made by the SDK. The x-speakeasy-retries extension supports the following properties:

Property
Type
Description
The retry strategy to use. Only
is currently supported.
Required
Yes
Type
Description
The configuration of the backoff strategy, if chosen.
Required
No
Type
Description
The initial interval to use for the backoff strategy (in milliseconds).
Required
No
Type
Description
The maximum interval between retries (in milliseconds).
Required
No
Type
Description
The maximum elapsed time to retry for (in milliseconds).
Required
No
Type
Description
The exponent used to increase the interval between retries.
Required
No
Type
Description
The HTTP status codes to retry on.
Required
Yes
Type
Description
Whether to retry any connection errors.
Required
No

The statusCodes property supports passing a list of distinct HTTP status codes or a wildcard range to retry requests on. For example, 5XX will retry requests on all status codes between 500 (inclusive) and 600 (exclusive).

Set the retryConnectionErrors property to true to configure retrying requests that fail due to network errors like DNS resolution errors or connection refused errors.

The defaults for the backoff strategy are:

  • initialInterval: 500
  • maxInterval: 60000
  • maxElapsedTime: 3600000
  • exponent: 1.5

Per-request Retries

Add the x-speakeasy-retries extension to any operation to override the global retry configuration for that operation, or to configure retries for the operation if retries aren’t defined globally. For example, you might want to configure retries for an operation on a different set of HTTP status codes or specify different intervals between retries.

Per-request retries are configured the same way as global retries.

SDK Usage Override

Users of the SDK can override the retry strategy globally or at the request level by providing a utils.RetryConfig object. This object supports most of the same properties as the x-speakeasy-retries extension, except for the status codes to retry on.

Global

To override the retry strategy globally, initialize the SDK object with the appropriate options parameter. In all cases, if no override is provided, the retry configuration provided in the OpenAPI document will be used.

In this example, we use the RetryConfig object to disable retries globally:

Request-Level Override

Any endpoints that support retries allow retry configuration to be overridden. In Go, override request-level retry configuration with operations.WithRetries. In Python and TypeScript, the optional retries is accepted.

Idempotency

For endpoints with a defined idempotency header, retries use the exact idempotency key provided for the initial request.

Respecting Retry-After

If an API returns an HTTP standard retry-after header, the SDK will respect that value as the retry interval as long as the time is in the future and below the max elapsed retry time. No configuration changes are needed to enable this; simply return a retry-after header from the API. This feature is currently supported in TypeScript with support for additional languages coming in the future.

Last updated on