Announcement: Updated default retry behavior (2026)

[luigi617]

This issue tracks the 2026 retry updates for AWS SDK for Kotlin. See the announcement blog post for the full story across all AWS SDKs

We're updating the standard retry strategy in the AWS SDK for Kotlin and the underlying smithy-kotlin runtime. This change brings the Kotlin SDK in line with other AWS SDKs, ensuring a more consistent retry experience across languages. The new values are specifically chosen to decrease failure rates and reduce unnecessary CPU usage and cost during partial or full outages. The update refines backoff timing, adds service-specific tuning for DynamoDB, introduces retry header support, and improves handling of long-polling operations.

Nothing is changing with the default standard retry behavior today. The new standard retry will be available to opt in for early testing in release 1.6.73, released on 05/13/2026, and will become the default in release 1.8.0, tentatively scheduled for Q1 2027.

Status

Opt-in available in	aws-sdk-kotlin version 1.6.73 and later
Opt-in flag	AWS_NEW_RETRIES_2026=true
Default rollout	Version 1.8.0, tentatively Q1 2027

What changed

When you set AWS_NEW_RETRIES_2026=true, the retry defaults within standard mode update. The retry mode itself does not change.

If you have explicitly configured max attempts or backoff, your value takes precedence for that setting.

Setting	Before	After
Transient (non-throttling) base delay	10 ms	50 ms
Throttling base delay	1,000 ms	1,000 ms (unchanged)
Scale factor	1.5	2.0
Max attempts	3	3 (unchanged)
Transient retry quota cost	10 tokens	14 tokens
Throttling retry quota cost	10 tokens	5 tokens
Other retryable quota cost	5 tokens	14 tokens
DynamoDB and DynamoDB Streams
Transient (non-throttling) base delay	10 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.

Backoff timing

The retry delay for a given attempt is calculated as:

delay = random(1 - jitter, 1) * min(baseDelay * scaleFactor ^ attemptNumber, maxBackoff)

Where attemptNumber is 0-indexed (the first retry uses attemptNumber = 0) and maxBackoff is 20 seconds (unchanged).

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.

Retry header: x-amz-retry-after

The SDK now honors the x-amz-retry-after response header, which allows services to recommend a specific backoff duration in milliseconds. The SDK will never wait less than its own calculated backoff, and never more than 5 seconds beyond it.

How to opt in

Update to aws-sdk-kotlin version 1.6.73 or later, then set the environment variable:

export AWS_NEW_RETRIES_2026=true

You can also set it as a JVM system property:

-Daws.newRetries2026=true

smithy-kotlin

For smithy-kotlin users not using the AWS SDK, the equivalent flag is:

export SMITHY_NEW_RETRIES_2026=true

Or as a JVM system property:

-Dsmithy.newRetries2026=true

AWS_NEW_RETRIES_2026 takes precedence. When it is set (to true or false), that value is used and SMITHY_NEW_RETRIES_2026 is ignored. Only when AWS_NEW_RETRIES_2026 is unset does the SDK check SMITHY_NEW_RETRIES_2026.

AWS_NEW_RETRIES_2026	SMITHY_NEW_RETRIES_2026	Result
true	any	New retry enabled
false	any	Current behavior
unset	true	New retry enabled
unset	false or unset	Current behavior

How to revert

During the opt-in period, remove the environment variable:

unset AWS_NEW_RETRIES_2026

After the default rollout (version 1.8.0, tentatively Q1 2027), the AWS_NEW_RETRIES_2026 flag will be removed. The updated behavior cannot be reverted because this SDK does not support legacy retry mode. You can override individual settings:

Setting	Can revert?	How
Max attempts	Yes	Set AWS_MAX_ATTEMPTS or configure in code.
Base backoff delay	Yes	Configure in code.
Scale factor	Yes	Configure in code.
Per-error-type backoff split (throttling vs non-throttling base delay)	Yes	Configure in code.
Retry quota token costs	Yes	Configure in code.
Long-polling backoff on depleted quota	Yes	Configure in code.

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

Where you might notice a difference

For most workloads, the change is invisible or strictly better. 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). 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 (previously 10). Other retryable errors cost 14 tokens (previously 5)
• 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, polling loops tighten during outages, spiking client CPU usage and generating additional load that can delay recovery. For details, see long-polling operations.

Overriding specific settings

You do not have to accept all changes as a bundle. If you opt in but want to keep a specific previous value, set it explicitly. Precedence applies per setting.

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

import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.smithy.kotlin.runtime.retries.StandardRetryStrategy

val client = DynamoDbClient.fromEnvironment {
    retryStrategy(StandardRetryStrategy) {
        maxAttempts = 9
    }
}

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

Feedback

If you run into any issues or have questions, please open an issue in aws-sdk-kotlin or comment on this discussion. Your feedback during the opt-in period directly shapes when and how we make this the default.