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)