Announcement: Updated default retry behavior (2026)

[millems]

Important

Update: Starting in aws-sdk-php version 3.403.3 (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 PHP 3.x. 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-php version 3.401.1 and later
Opt-in flag	AWS_NEW_RETRIES_2026=true (removed in version 3.403.3)
Default in	aws-sdk-php version 3.403.3 and later (released November 10, 2026)

What changed

Starting in version 3.403.3 (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. However, a retries array in code replaces both settings from environment variables and the config file. For example, with 'retries' => ['mode' => 'standard'], the client uses the default max attempts (3, or 4 for DynamoDB and DynamoDB Streams), even if you set AWS_MAX_ATTEMPTS. If you use standard or adaptive mode, the new backoff timing, retry quota costs, and DynamoDB max attempts still apply.

DynamoDB and DynamoDB Streams clients now read AWS_RETRY_MODE, AWS_MAX_ATTEMPTS, and the config file, which they previously ignored. A defaults_mode other than legacy no longer overrides your retry mode or max attempts.

Setting	Before	After
Default retry mode	legacy	standard
Transient (non-throttling) base delay	100 ms	50 ms
Throttling base delay	100 ms	1,000 ms
Max attempts	3	3 (unchanged)
Retry quota	None	500 tokens
Transient retry quota cost	None	14 tokens
Throttling retry quota cost	None	5 tokens
DynamoDB and DynamoDB Streams
Transient (non-throttling) base delay	No delay on the first retry, then 100 ms, 200 ms, …	25 ms
Throttling base delay	No delay on the first retry, then 100 ms, 200 ms, …	1,000 ms
Max attempts	11 (12 for DynamoDB Streams)	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-sdk-php version 3.401.1 or later, then set the environment variable:

export AWS_NEW_RETRIES_2026=true

The value must be exactly true (lowercase). The opt-in matches the new default, except that it doesn't retry HTTP 429 responses with an unrecognized error code, and a defaults_mode other than legacy still overrides your retry mode.

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

unset AWS_NEW_RETRIES_2026

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

export AWS_RETRY_MODE=legacy

Or in code:

use Aws\DynamoDb\DynamoDbClient;

$client = new DynamoDbClient([
    'region' => 'us-west-2',
    'retries' => [
        'mode' => 'legacy',
    ],
]);

With legacy mode, DynamoDB and DynamoDB Streams clients now also read AWS_MAX_ATTEMPTS and max_attempts from the config file, which they previously ignored. Without either, they use 11 max attempts. DynamoDB Streams previously used 12, so to keep 12, set AWS_MAX_ATTEMPTS=12 or 'retries' => ['mode' => 'legacy', 'max_attempts' => 12].

If you previously used standard or adaptive mode, or a defaults_mode other than legacy, legacy doesn't restore your previous behavior, because the updated implementation replaces the previous standard mode.

Where you might notice a difference

Most transient retries wait less. DynamoDB's first retry, previously immediate, now waits up to 25 ms. Throttling retries wait longer: up to 1,000 ms on the first retry, previously 100 ms (immediate for DynamoDB).

• Max attempts decreased. DynamoDB max attempts decreased from 11 to 4 (12 to 4 for DynamoDB Streams). If your workload relied on a higher retry count to eventually succeed, you may see more errors surfaced to your code. You can override max_attempts to restore your previous value.
• DynamoDB uses your global retry settings. If you set AWS_MAX_ATTEMPTS or max_attempts for other clients, DynamoDB and DynamoDB Streams clients now use it too.
• Explicit legacy mode for DynamoDB. If you set 'mode' => 'legacy' for a DynamoDB or DynamoDB Streams client without setting max_attempts, max attempts increase from 3 to 11.
• This SDK now has a retry quota. Legacy mode had no standardized retry quota. 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 errors). Unlike the previous standard mode, whose quota reset on every request (except for Amazon S3 clients), the quota is now shared per client. 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. The delay blocks the PHP process, so it also holds up other asynchronous requests in flight. For details, see long-polling operations.
• More errors are retried. Compared with legacy mode, the default now also retries RequestTimeout, RequestTimeoutException, PriorRequestNotComplete, and LimitExceededException errors, errors that the service model marks as retryable, and HTTP 429 responses with an unrecognized error code. DynamoDB TransactionInProgressException errors count as throttling errors.
• 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 do not have to accept all changes as a bundle. You can keep a previous retry mode or max attempts by setting it explicitly. Precedence applies per setting across environment variables and the config file. In code, a retries array must include mode. ['max_attempts' => 11] alone throws an InvalidArgumentException. An integer such as 'retries' => 10 is accepted, but it selects legacy mode with that many retries.

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

use Aws\DynamoDb\DynamoDbClient;

$client = new DynamoDbClient([
    'region' => 'us-west-2',
    'retries' => [
        'mode' => 'standard',
        'max_attempts' => 11, // 12 for DynamoDB Streams
    ],
]);

The retry quota still applies. During widespread transient failures, a client stops retrying after about 35 retries in total, whatever max_attempts is, until successful requests refill the quota.

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 aws-sdk-php version 3.403.3 (released November 10, 2026), the AWS SDK for PHP 3.x 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 when you upgrade, with two additions. HTTP 429 responses with an unrecognized error code are now retried as throttling errors, and a defaults_mode other than legacy no longer overrides AWS_RETRY_MODE, AWS_MAX_ATTEMPTS, or the config file's retry settings. You can remove the variable afterward.
• Haven't opted in? You get the updated behavior when you upgrade to 3.403.3 or later. To test it first, update to aws-sdk-php version 3.401.1 or later and set AWS_NEW_RETRIES_2026=true in a non-production environment.
• Set AWS_NEW_RETRIES_2026=false? In 3.403.3 and later, the SDK ignores the variable, so it no longer keeps the previous behavior.

Restoring previous behavior

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

export AWS_RETRY_MODE=legacy

In legacy mode, DynamoDB Streams clients use 11 max attempts instead of 12. See How to revert in the description for details and 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.