Announcement: Updated default retry behavior (2026)

[millems]

Important

Update: Starting in aws-sdk-swift version 1.8.24 (released November 10, 2026), the updated retry behavior is the default and the AWS_NEW_RETRIES_2026 environment variable is removed. To test the updated behavior before you upgrade, see How to opt in early. To restore previous behavior after you upgrade, see How to revert.

This issue tracks the 2026 retry updates for AWS SDK for Swift. See the announcement blog post for the full story across all AWS SDKs, including how to tell if you are affected.

Status

Opt-in available in	aws-sdk-swift version 1.7.9 and later
Opt-in flag	AWS_NEW_RETRIES_2026=true (removed in version 1.8.24)
Default in	aws-sdk-swift version 1.8.24 and later (released November 10, 2026)

What changed

Starting in version 1.8.24 (or earlier, if you set AWS_NEW_RETRIES_2026=true), the default retry mode changes from legacy to standard, and the retry defaults update per the table below. In this SDK, legacy and standard modes behave the same, including the DynamoDB max attempts default. adaptive mode also gets the updated defaults.

If you have explicitly configured max attempts (maxAttempts in code, AWS_MAX_ATTEMPTS, or max_attempts), your value takes precedence, unless you also supply your own retryStrategyOptions, whose maxRetriesBase sets max attempts. Your own retryStrategyOptions use the updated behavior too, unless you create them with useNewRetries2026: false, which keeps the previous base delays and retry quota costs. If you use builder(), it replaces the retryStrategyOptions in the config that you pass to withConfig(_:). To set them on a builder, add .withPlugin(RetryPlugin(retryStrategyOptions: ...)).

Setting	Before	After
Transient (non-throttling) base delay	1,000 ms	50 ms
Throttling base delay	1,000 ms	1,000 ms (unchanged)
Max attempts	3	3 (unchanged)
Transient retry quota cost	5 tokens (10 for timeouts)	14 tokens
DynamoDB and DynamoDB Streams
Transient (non-throttling) base delay	1,000 ms	25 ms
Throttling base delay	1,000 ms	1,000 ms (unchanged)
Max attempts	3	4

DynamoDB defaults use a shorter base delay to match its low-latency profile. The additional attempt keeps the last retry's maximum backoff the same as the general default.

DynamoDB and DynamoDB Streams clients default to 4 max attempts however you create them.

Transient errors (such as 500s and connection resets) now use a much shorter backoff than throttling errors (where the service asks you to slow down). For details on backoff timing, error classification, and the retry quota, see Retry behavior in the AWS SDKs. For retry mode selection and configuration options, see Retry behavior in the AWS SDKs.

How to opt in early

Update to aws-sdk-swift version 1.7.9 or later, then set the environment variable:

export AWS_NEW_RETRIES_2026=true

Only the lowercase value true enables the opt-in.

The opt-in doesn't preview some changes in 1.8.24: retries of HTTP 429 responses without a modeled error, the 4-attempt DynamoDB default for clients created with region: or builder() or in legacy mode, and the updated behavior for your own retryStrategyOptions.

In version 1.8.24 and later, the updated behavior is the default and the SDK ignores AWS_NEW_RETRIES_2026. You can remove it from your configuration after you upgrade.

How to revert

In versions earlier than 1.8.24, remove the environment variable:

unset AWS_NEW_RETRIES_2026

In version 1.8.24 and later, the updated behavior is the default and the SDK ignores AWS_NEW_RETRIES_2026, so unsetting it or setting it to false doesn't restore the previous behavior. legacy retry mode doesn't restore it either. To restore the previous backoff timing, max attempts, and retry quota costs for a client, supply your own retryStrategyOptions created with useNewRetries2026: false:

import AWSDynamoDB
import SmithyRetries
import SmithyRetriesAPI

let config = try await DynamoDBClient.DynamoDBClientConfig(
    retryStrategyOptions: RetryStrategyOptions(
        backoffStrategy: ExponentialBackoffStrategy(),
        maxRetriesBase: 2,          // 3 attempts; this is also the default
        useNewRetries2026: false
    )
)
let client = DynamoDBClient(config: config)

If you create clients with builder(), pass the same options in a RetryPlugin:

import AWSDynamoDB
import ClientRuntime   // for RetryPlugin
import SmithyRetries
import SmithyRetriesAPI

let client = try await DynamoDBClient.builder()
    .withPlugin(RetryPlugin(retryStrategyOptions: RetryStrategyOptions(
        backoffStrategy: ExponentialBackoffStrategy(),
        maxRetriesBase: 2,
        useNewRetries2026: false
    )))
    .build()

These options restore 3 attempts, a 1-second base delay for every error, and retry quota costs of 5 tokens (10 for timeouts), for DynamoDB too. AWS_MAX_ATTEMPTS and maxAttempts have no effect on a client with its own retryStrategyOptions. Three changes stay on: long-polling backoff, retries of HTTP 429 responses without a modeled error, and x-amz-retry-after handling. With these options, an x-amz-retry-after value replaces the computed backoff, with no upper limit.

To keep the updated behavior and change only max attempts, set maxAttempts, AWS_MAX_ATTEMPTS, or max_attempts. DynamoDB clients use your value as is, in every retry mode.

If this is a concern for your use case, please let us know in this issue.

Where you might notice a difference

Transient errors recover faster because the base delay is significantly shorter.

• Retry quota activates sooner for transient errors. Each transient retry costs 14 tokens (previously 5 for most errors and 10 for timeouts). During sustained transient failures (such as 500s and connection resets), the retry quota triggers at a lower failure rate than the previous version of standard mode. Throttling retries cost 5 tokens.
• Long-polling operations now back off when the retry quota is depleted. Operations like SQS.ReceiveMessage apply a backoff delay before returning an error, even when retries are blocked. Without this, a polling loop would send its next request immediately after each error, spiking client CPU usage and generating additional traffic. You can't turn this off. For details, see long-polling operations.
• More HTTP 429 responses are retried. An HTTP 429 response without a modeled error is now retried as a throttling error.
• The SDK honors the x-amz-retry-after response header. When a service sends it, the SDK waits at least its own computed backoff and at most 5 seconds longer.
• The resolved retry mode is standard. config.awsRetryMode now reads .standard by default. AWSRetryFeatures.isNewRetries2026Enabled is deprecated and always true.

Overriding specific settings

If you want to keep a specific previous value, set max attempts explicitly, or supply your own retryStrategyOptions. Your own options use the updated behavior unless you create them with useNewRetries2026: false, which restores the previous base delays and retry quota costs. Long-polling backoff can't be turned off. Max attempts follows the usual precedence (code, then AWS_MAX_ATTEMPTS, then max_attempts). Your own retryStrategyOptions replace all retry settings at once, so maxAttempts has no effect when you pass them.

For example, to use the new backoff timing but keep a higher DynamoDB max attempts:

import AWSDynamoDB

let config = try await DynamoDBClient.DynamoDBClientConfig(maxAttempts: 9)

let client = DynamoDBClient(config: config)

Set maxAttempts in the initializer. Changing config.maxAttempts afterward doesn't affect clients created with DynamoDBClient(config:).

For the full list of configurable settings and their precedence, see Retry behavior in the AWS SDKs.

Feedback

If you encounter unexpected behavior or have questions, comment on this issue. If you need a previous value that you can't configure, let us know here.

[dayaffe]

Use with opt-in flag AWS_NEW_RETRIES_2026=true is now available from version 1.7.9!

[pulimsr]

Update: The updated retry behavior is now the default

Starting in aws-sdk-swift version 1.8.24 (released November 10, 2026), the AWS SDK for Swift uses the updated retry behavior by default, and the AWS_NEW_RETRIES_2026 environment variable is removed. For the announcement across all AWS SDKs, see Updated retry behavior is now the default for AWS SDKs and tools.

The opt-in is available in aws-sdk-swift version 1.7.9 and later.

What this means for you

• Already set AWS_NEW_RETRIES_2026=true? Retry timing and quota costs stay the same when you upgrade, with these exceptions. DynamoDB clients now use an AWS_MAX_ATTEMPTS or max_attempts value below 4 as is. DynamoDB clients in legacy mode or created with DynamoDBClient(region:) or builder() now default to 4 attempts. Your own retryStrategyOptions now use the updated behavior. HTTP 429 responses without a modeled error are now retried as throttling. You can remove the variable afterward.
• Haven't opted in? You get the updated behavior when you upgrade to 1.8.24 or later. To test it first, update to aws-sdk-swift version 1.7.9 or later and set AWS_NEW_RETRIES_2026=true in a non-production environment.
• Set AWS_NEW_RETRIES_2026=false? In 1.8.24 and later, the SDK ignores the variable, so it no longer keeps the previous behavior.

Restoring previous behavior

In this SDK, legacy retry mode doesn't restore the previous behavior. To restore the previous backoff timing and retry quota costs, supply your own retryStrategyOptions created with useNewRetries2026: false. Long-polling backoff, retries of HTTP 429 responses without a modeled error, and x-amz-retry-after handling stay on. See How to revert in the description for details. If you need a previous value that you can't configure, let us know here.

We've updated the description with the new version information and revert instructions, and corrected some of the before-and-after values. If you run into unexpected behavior, comment here.