Announcement: Updated default retry behavior (2026)

[millems]

Important

Update: Starting with the November 10, 2026 release (aws-config version 1.13.2), the updated retry behavior is the default for every client that uses BehaviorVersion::v2026_11_10() or later, such as BehaviorVersion::latest(), 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 Rust. 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-config version 1.8.17 and later
Opt-in flag	AWS_NEW_RETRIES_2026=true (removed in aws-config version 1.13.2)
Default in	aws-config version 1.13.2, aws-smithy-runtime-api version 1.21.0, and aws-smithy-runtime version 1.16.3 and later (released November 10, 2026), for clients that use BehaviorVersion::v2026_11_10() or later, such as BehaviorVersion::latest()

What changed

Starting with the November 10, 2026 release (or earlier, if you set AWS_NEW_RETRIES_2026=true), the retry defaults within standard and adaptive modes update for clients that use BehaviorVersion::v2026_11_10() or later, whether or not you build them with aws-config. The retry mode itself does not change. The DynamoDB and DynamoDB Streams defaults also need the aws-sdk-dynamodb and aws-sdk-dynamodbstreams versions from that release.

AWS_MAX_ATTEMPTS and the profile max_attempts setting take precedence for max attempts, DynamoDB clients included. A RetryConfig that you set in code, on aws_config::defaults() or on a service config, keeps the updated behavior. Its max attempts, initial backoff (throttling only), and max backoff replace the defaults. On DynamoDB, such a config also replaces the 4-attempt default with its own max attempts, which is 3 unless you call with_max_attempts.

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	10 tokens (5 for modeled retryable server errors)	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 comparable to the general default.

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-config version 1.8.17 or later. For adaptive mode, use aws-config version 1.10.1 or later, which requires aws-smithy-runtime version 1.12.1 or later. The service crates carry the DynamoDB defaults and the long-polling backoff, so also update any of these that you use to at least the version shown: aws-sdk-dynamodb 1.112.0, aws-sdk-sqs 1.99.0, aws-sdk-sfn 1.105.0, aws-sdk-swf 1.101.0. Then set the environment variable:

export AWS_NEW_RETRIES_2026=true

The opt-in doesn't cover everything in the default. With the opt-in, clients built without aws-config and clients that set a RetryConfig in code keep the previous behavior, DynamoDB ignores AWS_MAX_ATTEMPTS, and DynamoDB Streams uses the general defaults. The HTTP 429 change in Where you might notice a difference ships only with the default.

In aws-config version 1.13.2 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 aws-config earlier than 1.13.2, remove the environment variable:

unset AWS_NEW_RETRIES_2026

In aws-config version 1.13.2 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. To restore the previous retry behavior, pin BehaviorVersion::v2026_01_12(). This restores every previous retry value except one: an HTTP 429 response with no recognized error code is now retried as a throttling error in every behavior version.

// At the top of your crate root (main.rs or lib.rs).
// `v2026_01_12` is deprecated. This attribute silences the deprecation warning.
#![allow(deprecated)]

use aws_config::BehaviorVersion;

let sdk_config = aws_config::defaults(BehaviorVersion::v2026_01_12())
    .load()
    .await;
let client = aws_sdk_dynamodb::Client::new(&sdk_config);

For clients that you build with a service Config::builder() instead of aws-config, set .behavior_version(BehaviorVersion::v2026_01_12()) on that builder.

Don't pin anything older than v2026_01_12. That also reverts the default connect timeout, the default HTTP client, and default retries for clients built without aws-config.

This SDK doesn't support legacy retry mode. Setting AWS_RETRY_MODE=legacy (or retry_mode = legacy in a profile) makes aws_config::defaults(...).load() panic.

To keep the updated behavior and change only some settings, see Overriding specific settings.

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 10 for 5xx, timeout, and connection errors, and 5 for modeled retryable server errors). 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. SQS ReceiveMessage, Step Functions GetActivityTask, and SWF PollForActivityTask and PollForDecisionTask 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. For details, see long-polling operations.
• More HTTP 429 responses are retried. An HTTP 429 response with no recognized error code is now retried as a throttling error, in every behavior version.
• Connections are reused after transient errors. Previously, a 5xx response or a timeout closed the pooled connection. To close it again, set .with_reconnect_mode(ReconnectMode::ReconnectOnTransientError) on your RetryConfig.
• x-amz-retry-after delays are bounded. When a service sends the header, the SDK waits at least its own computed backoff and at most 5 seconds longer. Previously, the only limit was the 20-second max backoff.
• BehaviorVersion::v2026_01_12() is deprecated. Code that pins it gets a deprecation warning, and builds that deny warnings fail.

Overriding specific settings

You do not have to accept all changes as a bundle, but you can't revert some of them individually. In code, RetryConfig lets you set max attempts (with_max_attempts), the maximum backoff (with_max_backoff), and the reconnect mode (with_reconnect_mode), and you can supply a custom RetryPartition with its own token bucket (capacity, costs, and refill). While the updated behavior is on, with_initial_backoff sets only the throttling base delay. If you keep the rest of the updated behavior, you can't restore the previous 1,000 ms transient base delay or the previous adaptive mode rate-limiter behavior, and you can't remove the new bounds on x-amz-retry-after delays or the long-polling backoff.

Precedence applies per setting for environment variables and profile settings, DynamoDB included. A RetryConfig set on the loader replaces the environment and profile retry settings with its own values, but it keeps the updated behavior. You can set it on the loader, on a client, or per operation.

For example, to keep the new backoff timing and allow 9 attempts for one DynamoDB operation:

use aws_config::BehaviorVersion;
use aws_config::retry::RetryConfig;

let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let client = aws_sdk_dynamodb::Client::new(&config);

let tables = client
    .list_tables()
    .customize()
    .config_override(
        aws_sdk_dynamodb::Config::builder()
            .retry_config(RetryConfig::standard().with_max_attempts(9)),
    )
    .send()
    .await?;

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.