Announcement: Updated default retry behavior (2026)

[millems]

Important

Update: Starting in boto3 and botocore version 1.44.0 (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 the previous default behavior after you upgrade, see How to revert.

This issue tracks the 2026 retry updates for AWS SDK for Python (Boto3). 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	boto3 and botocore version 1.43.3 and later
Opt-in flag	AWS_NEW_RETRIES_2026=true (removed in version 1.44.0)
Default in	boto3 and botocore version 1.44.0 and later (released November 10, 2026)

What changed

Starting in version 1.44.0 (or earlier, if you set AWS_NEW_RETRIES_2026=true), the default retry mode changes from legacy to standard. Several other retry defaults also update. The standard mode adds a retry quota that limits retries when failures are widespread, so your application fails fast instead of waiting on retries that are unlikely to succeed. This also helps service disruptions resolve faster by reducing retry traffic.

If you have explicitly configured a retry mode or max attempts, your value takes precedence for that setting. If you use standard or adaptive mode, the new backoff timing, retry quota costs, and DynamoDB max attempts still apply. See Where you might notice a difference.

Setting	Before	After
Default retry mode	legacy	standard
Transient (non-throttling) base delay	1,000 ms	50 ms
Throttling base delay	1,000 ms	1,000 ms (unchanged)
Max attempts	5	3
Retry quota	None	500 tokens
Transient retry quota cost	None	14 tokens
Throttling retry quota cost	None	5 tokens
DynamoDB
Transient (non-throttling) base delay	50 ms	25 ms
Throttling base delay	50 ms	1,000 ms
Max attempts	10	4
DynamoDB Streams
Transient (non-throttling) base delay	1,000 ms	25 ms
Throttling base delay	1,000 ms	1,000 ms (unchanged)
Max attempts	5	4

DynamoDB defaults use a shorter base delay to match its low-latency profile. For transient errors, the additional attempt keeps the last retry's maximum backoff the same as 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 boto3 and botocore version 1.43.3 or later, then set the environment variable:

export AWS_NEW_RETRIES_2026=true

botocore reads the variable once, when it's imported, so set it before your application starts.

In version 1.44.0 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.44.0, remove the environment variable:

unset AWS_NEW_RETRIES_2026

In version 1.44.0 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 default behavior, set the retry mode to legacy:

export AWS_RETRY_MODE=legacy

Or in code:

import boto3
from botocore.config import Config

config = Config(
    retries={
        'mode': 'legacy'
    }
)

client = boto3.client('dynamodb', config=config)

Setting the retry mode to legacy restores the previous default only. If you explicitly set standard or adaptive mode before, you can't restore that mode's previous backoff timing (1 s base delay) or retry quota costs (5 tokens, or 10 for connection and read timeouts).

Where you might notice a difference

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

• Max attempts decreased from 5 to 3 (10 to 4 for DynamoDB, 5 to 4 for DynamoDB Streams). If you explicitly use standard mode, DynamoDB and DynamoDB Streams max attempts increase from 3 to 4. If your workload relied on a higher retry count to eventually succeed, you may see more errors surfaced to your code. To restore your previous value, set max attempts to 5 with total_max_attempts in code, the AWS_MAX_ATTEMPTS environment variable, or max_attempts in ~/.aws/config. To restore 10 for DynamoDB only, set total_max_attempts on the DynamoDB client. The environment variable and config file apply one value to all clients.
• The default retry mode now has a retry quota. Standard mode already had one, but legacy mode, the previous default, had none. The SDK would retry up to the max attempt count regardless of how many requests were failing. Standard mode tracks a token budget and returns errors directly when failures are widespread, so your application fails fast and frees up resources for requests that can succeed. For details, see retry quota.
• Retry quota activates sooner for transient errors. Each transient retry costs 14 tokens (in explicit standard mode, previously 5, or 10 for connection and read 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. For details, see long-polling operations.
• Some errors retry differently. An HTTP 429 response whose error code isn't modeled for the operation is now retried as a throttling error. Compared with legacy mode, standard mode doesn't retry S3 BadDigest errors or HTTP 509 responses other than BandwidthLimitExceeded.
• 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.

Overriding specific settings

You can override the retry mode and max attempts individually. You can't configure backoff timing or retry quota costs. To keep your previous max attempts, set it explicitly. Precedence applies per setting.

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

import boto3
from botocore.config import Config

config = Config(
    retries={
        'total_max_attempts': 10,
        'mode': 'standard'
    }
)

client = boto3.client('dynamodb', config=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.

[Alan4506]

Update: The updated retry behavior is now the default

Starting in boto3 and botocore version 1.44.0 (released November 10, 2026), the AWS SDK for Python (Boto3) 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 default retry behavior for AWS SDKs and tools.

What this means for you

• Already set AWS_NEW_RETRIES_2026=true? Your retry behavior stays the same, with one addition: an HTTP 429 response whose error code isn't modeled for the operation is now retried as a throttling error. You can remove the variable after you upgrade.
• Haven't opted in? You get the updated behavior when you upgrade to 1.44.0 or later. To test it first, update to boto3 and botocore version 1.43.3 or later and set AWS_NEW_RETRIES_2026=true in a non-production environment.
• Set AWS_NEW_RETRIES_2026=false? In 1.44.0 and later, the SDK ignores the variable, so it no longer keeps the previous behavior.

Restoring previous behavior

In 1.44.0 and later, set the retry mode to legacy to restore the previous default behavior:

export AWS_RETRY_MODE=legacy

This doesn't restore the previous backoff timing or retry quota costs of explicit standard or adaptive mode. See How to revert in the description for other ways to set it.

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.