Configure retry using the SDK for Swift

Calls to AWS services occasionally encounter problems or unexpected situations. Certain types of errors, such as throttling or transient errors, might be successful if the call is retried.

This page describes how to configure automatic retries with the AWS SDK for Swift.

Default retry configuration

By default, every service client is automatically configured with a standard retry strategy. The default configuration tries each action up to three times (the initial attempt plus two retries). The intervening delay between each call is configured with exponential backoff and random jitter to avoid retry storms. This configuration works for the majority of use cases but may be unsuitable in some circumstances, such as high-throughput systems.

The SDK attempts retries only on retryable errors. Examples of retryable errors are socket timeouts, service-side throttling, concurrency or optimistic lock failures, and transient service errors. Missing or invalid parameters, authentication/security errors, and misconfiguration exceptions are not considered retryable.

You can customize the standard retry strategy by setting the maximum number of attempts and the rate limiting strategy to use. To change the retry configuration, create a structure of type RetryStrategyOptions with the desired configuration, then assign it to the retryStrategy property of the service configuration. For details on how to configure a service, see Customize AWS service client configurations.

Configure retry

Warning

There are other options available in RetryStrategyOptions beyond those covered here, such as the backoffStrategy (the algorithm used to determine how long to wait after each attempt). These options are currently intended only for future expansion, and should not be used unless advised to do so by an AWS representative.

Maximum number of retries

You can customize the maximum number of attempts by setting the value of RetryStrategyOptions.maxRetriesBase. The default value is 2, which allows for a total of three attempts to be made (the initial attempt plus up to two retries).

Rate limiting mode

The rate limiting mode can be set by changing the RetryStrategyOptions structure's rateLimitingMode. The available values are provided by the enum RateLimitingMode.

Standard

The standard rate limiting mode is the default. In this mode, requests may be sent immediately, and are not delayed for rate limiting when throttling is detected.

In standard mode, requests are only delayed according to the backoff strategy in use.

Adaptive

In the adaptive rate limiting mode, initial and retry requests may be delayed by an additional amount when throttling is detected. This is sometimes called "client-side rate limiting" mode, and is available opt-in. You should only use adaptive mode when advised to do so by an AWS representative.

In adaptive retry mode, requests are delayed when the server indicates that requests are being throttled.

Example

This example creates an Amazon S3 client configured to retry five times (up to a total of six attempts), using the adaptive rate limiting mode.

        let config: S3Client.S3ClientConfiguration

        // Create an Amazon S3 client configuration object that specifies the
        // adaptive retry mode and the base maximum number of retries as 5.

        do {
            config = try await S3Client.S3ClientConfiguration(
                retryStrategyOptions: RetryStrategyOptions(
                    maxRetriesBase: 5,
                    rateLimitingMode: .adaptive
                )
            )
        } catch {
            print("Error: Unable to create configuration")
            dump(error)
            exit(1)
        }

        // Create an Amazon S3 client using the configuration created above.

        let client = S3Client(config: config)