Announcing updated retry behavior for AWS SDKs and Tools

When your application calls an AWS service and the request fails with a retryable error, the AWS SDK retries it automatically. The retry behavior controls how long the SDK waits between attempts and when it gives up. Most of this happens in the background, but it directly affects how your application experiences errors and latency.

Until today, retry defaults varied across SDKs. Some waited too long before retrying transient errors, and others would keep retrying instead of failing fast, even during sustained outages. The updated behavior addresses both issues with consistent defaults across all AWS SDKs.

You can opt in to the updated behavior starting today across AWS SDKs, the AWS Command Line Interface (AWS CLI), and AWS Tools for PowerShell. These changes will become the default in November 2026.

This post covers what changed, how to tell if you’re affected, how to opt in, and how to revert.

What changed

This update changes how standard and adaptive (a rate-limiting mode built on standard) retry modes handle failed requests. It also makes standard the default for SDKs that had previously defaulted to legacy.

Most SDKs use the standard retry mode by default. It includes a retry quota, exponential backoff with jitter, and a standard set of retryable errors. Some older SDKs still default to legacy mode, which lacks a retry quota and behaves inconsistently across SDKs. For a full comparison, see Retry behavior.

Retry quota updates

standard mode has always included a retry quota: a token bucket that tracks how many retries your client is making. When failures are persistent, the budget depletes and the SDK stops retrying. At scale, this helps outages resolve faster (retry traffic from many clients can delay recovery) and reduces your client-side latency by failing fast instead of waiting through retries that are unlikely to succeed.

If you were using legacy mode, this is new to you. legacy mode had no standardized retry quota, so the SDK would keep retrying up to the max attempt count regardless of how many requests were failing.

In the updated standard mode, each transient error retry costs 14 tokens (up from 5 in the previous version of standard mode). Retries after throttling responses cost 5 tokens. The higher cost for transient errors means the quota engages sooner during sustained outages, letting the service recover faster. For a deeper look at how the retry quota works, see Retry quota (token bucket).

Faster retries for transient errors

The first retry after a transient error is now much faster, about 25 ms on average for a brief HTTP 503 response, down from hundreds of milliseconds or more.

standard mode now uses different backoff delays depending on the type of error:

• Transient errors (connection resets, DNS failures, HTTP 500/502/503/504): 50 ms base delay. These errors are typically short-lived, making them good candidates for immediate retry.
• Throttling errors (where the service asks you to slow down): 1,000 ms base delay. A longer delay gives the service time to recover capacity.

Previously, each SDK applied the same base delay regardless of error type, but that delay varied across SDKs, from 10 ms to 1,000 ms.

Amazon DynamoDB tuning

Amazon DynamoDB and Amazon DynamoDB Streams use a shorter base backoff delay (25 ms instead of 50 ms) to match their low-latency profile. These clients default to 4 max attempts. The additional attempt keeps the last retry’s maximum backoff comparable to other services. Previous defaults varied by SDK (up to 10 max attempts in some SDKs). For details, see DynamoDB in the retry behavior documentation.

Long-polling operations

Long-polling operations (such as the Amazon SQS ReceiveMessage operation) now apply a backoff delay before returning an error when the retry quota is depleted. Without this, a depleted quota returns the error immediately, which can cause polling loops to tighten, spiking CPU usage on the client and generating additional load on the service. For details, see Long-polling operations documentation.

Does this impact me?

This update changes behavior within standard and adaptive retry modes. Whether you’re affected depends on your current configuration:

• No explicit retry configuration at all? You will see all the changes after you opt in (or after the default rollout in November 2026). For SDKs that currently default to legacy mode (Java, Python, Ruby, PHP, C++, and the AWS CLI), this also switches the default to standard, which adds a retry quota.
• Explicitly set retry mode to standard or adaptive? You will see the new backoff timing, retry quota costs, and DynamoDB defaults. Your mode choice doesn’t change, but how these modes behave does.
• Explicitly set max_attempts or backoff settings? Those specific values stay as you configured them. Other settings you didn’t override (such as retry quota costs and DynamoDB defaults) will still update to the new defaults.
• Explicitly set retry mode to legacy? No changes. legacy mode is unchanged.
• Haven’t set AWS_NEW_RETRIES_2026=true? No changes until the default rollout in November 2026.

How to opt in

Set the following environment variable:

export AWS_NEW_RETRIES_2026=true

The flag works across all AWS SDKs that have released support. See SDK availability and GitHub issues below for which SDKs support the flag today.

We recommend testing on a non-production workload first.

Where you might notice a difference

For most workloads, the update is invisible or an improvement. Transient errors recover faster and you don’t need to change any code.

A few things to watch for:

• Max attempts may have decreased. Some SDKs previously defaulted to more than 3 max attempts. If your workload relied on a high retry count to eventually succeed, you may see more errors surfaced to your application. You can override max_attempts to restore your previous value.
• Some SDKs gain a retry quota for the first time. SDKs that previously defaulted to legacy mode had no standardized retry quota. The SDK will retry up to the max attempt count regardless of how many requests were failing. With standard mode, the SDK tracks a 500-token budget and stops retrying during sustained failures. Your application sees errors sooner during prolonged outages, but it also frees up threads and connections instead of waiting on retries that are unlikely to succeed.
• The retry quota activates sooner for transient errors. The higher transient retry cost means the quota depletes at a lower failure rate during sustained transient failures, such as a wave of 500 responses.

For SDK-specific before and after values, see your SDK’s GitHub tracking issue in the table below.

How to revert

Remove or unset the opt-in environment variable:

unset AWS_NEW_RETRIES_2026

After the default rollout in November 2026, the opt-in flag is ignored. To revert at that point, override individual settings such as max_attempts or backoff configuration. See your SDK’s GitHub tracking issue for revert instructions specific to your SDK.

For SDKs that support legacy mode (Java, Python, Ruby, PHP, C++, and the AWS CLI), you can also restore the previous behavior in a single setting:

export AWS_RETRY_MODE=legacy

SDK availability and GitHub issues

Eight SDKs support the opt-in flag today. Six more are coming in the following weeks.

Each tracking issue includes: minimum SDK version, before-and-after defaults, code examples, and a feedback section.

Conclusion

This update brings consistent, faster retry defaults across all AWS SDKs. You can opt in today by setting AWS_NEW_RETRIES_2026=true and revert at any time if you need to. We encourage you to try it on a non-production workload first, then roll it out to production before the defaults change in November 2026. If you don’t opt in before then, the new behavior will apply automatically.

Give us feedback

If you run into unexpected behavior, or if the changes work well for you, comment on your SDK’s GitHub tracking issue. Your feedback during the opt-in window helps us make the default rollout better for everyone.

Learn more

• Retry behavior: retry mode selection, settings, and configuration precedence.
• How retries work: backoff formula, error classification, retry quota mechanics, and service-specific behavior.