API Retry Strategy

OUTSCALE SDKs for our APIs include built-in support for automatic retries with exponential backoff when encountering transient HTTP errors.

Retry logic is currently implemented only in the Python SDK, starting v0.35.0. Support for other SDKs is planned for future releases.

General Information

The SDK automatically retries requests that fail with the following HTTP status codes:

  • HTTP 429 Too Many Requests

    • Code 24 - ErrorOperationThrottledPerAccount: Request rate exceeded.

    • Code 25 - ErrorOperationThrottledPerCall: Request rate exceeded.

  • HTTP 500 Internal Server Error – Temporary server issue.

  • HTTP 503 Service Unavailable – ErrorOperationThrottledWholePlatform: Request rate exceeded.

For more information, see the Error Codes Reference page.

The retry mechanism is based on the behavior of urllib3.util.Retry. By default, it is configured as follows:

  • Maximum retries: 3

  • Backoff factor: 1

  • Backoff jitter: 3 s

Exponential Backoff

Exponential backoff is a strategy used to manage retries after the API returns a limit code.

The delay between each retry attempt increases exponentially. The rate limit is configured per API call per account. To help mitigate concurrency issues when using a multithreaded program making API calls, jitter is added to the strategy.

It is calculated as follows:

{backoff factor} * (2 ** ({number of previous retries}))

Example of backoff and jitter settings:

Retry Attempt Wait Time (in seconds)

1st retry

Between 0 s and 3 s

2nd retry

Between 2 s and 5 s

3rd retry

Between 4 s and 7 s

Retry Customization

The retry behavior can be customized. You need to add or modify the following parameters:

  • max_retries: The maximum number of retry attempts before the request fails.

  • retry_backoff_factor: The multiplier for the exponential backoff delay.

  • retry_backoff_jitter: A value added to the delay to avoid all retries happening at the same time in multithreaded scenarios.

Customize the Python SDK

Example of customization for osc-sdk-python file:

    "eu2": {
        "access_key": "XXXX",
        "region_name": "eu-west-2",
        "secret_key": "XXXX",
        "max_retries": 3,
        "retry_backoff_factor": 1,
        "retry_backoff_jitter": 3,
    },

Customize the Gateway Object

Example of customization for the Gateway object:

gw = Gateway(
    **{
        "profile": "eu2",
        "max_retries": 3,
        "retry_backoff_jitter": 8,
        "retry_backoff_factor": 3,
    }
)

Related Page

Export to PDF