Introduction

Boto3 lets you control retry behavior through Botocore configuration. That matters when you need to tune how aggressively the SDK responds to throttling, transient network failures, or service-side retryable errors.

The key detail is that retries are configured on the client or through shared AWS configuration, not by passing an ad hoc retry count to individual API calls. Once you know where that setting lives, the change is straightforward.

Configure Retries with Config

The most direct way is to create a botocore.config.Config object and pass a retries dictionary when building the client.

1import boto3
2from botocore.config import Config
3
4config = Config(
5    retries={
6        "mode": "standard",
7        "total_max_attempts": 10,
8    }
9)
10
11s3 = boto3.client("s3", config=config)
12
13response = s3.list_buckets()
14print(response["Buckets"])

In this example, total_max_attempts counts the initial request plus retries. So a value of 10 means one original request and up to nine retries, depending on the error and retry mode.

Understand Retry Modes

Botocore supports retry modes such as legacy, standard, and adaptive.

• 'legacy preserves older SDK behavior.'
• 'standard is the normal modern choice for most applications.'
• 'adaptive adds client-side rate adaptation and can help under sustained throttling conditions.'

Unless you have a reason to match older behavior, standard is usually the safest default because it aligns with current AWS SDK retry handling more closely than legacy.

max_attempts Versus total_max_attempts

This is where confusion often appears. Botocore supports both max_attempts and total_max_attempts, but they are not interpreted the same way in every context.

For client Config, total_max_attempts is the clearest option because it expresses the full number of attempts, including the initial request. That makes the resulting behavior easier to reason about and aligns with the shared AWS configuration setting AWS_MAX_ATTEMPTS.

A practical rule is simple: if you are writing new code, prefer total_max_attempts.

Shared Configuration and Environment Variables

If you want the setting to apply broadly instead of to one client, you can configure retries through the AWS shared config file or environment variables.

Example environment variables:

export AWS_RETRY_MODE=standard
export AWS_MAX_ATTEMPTS=10

Those values influence clients created by Boto3 without repeating the retry configuration in every source file. This is useful in containerized deployments or shared runtime environments where retry policy should be centrally managed.

When Higher Retry Counts Help

Increasing retries can help when your application sees occasional throttling or short-lived network instability. It is less helpful when requests are failing for permanent reasons such as invalid credentials, access denied errors, or malformed parameters.

More retries also mean longer worst-case latency. If the call is on a request path with a strict timeout budget, a large retry count can turn a quick failure into a slow one. Good retry settings balance resilience with response-time expectations.

Common Pitfalls

• Setting retries on a session object and expecting every existing client to update automatically. Retry policy is fixed when the client is created.
• Confusing retryable failures with permanent failures such as authentication errors.
• Using a very high retry count without considering the latency cost.
• Mixing legacy and standard behavior across services without realizing it.
• Preferring max_attempts without understanding how the count is interpreted. For new code, total_max_attempts is usually clearer.

Summary

• Configure Boto3 retries with botocore.config.Config.
• Prefer total_max_attempts for clear attempt counting.
• Use standard retry mode unless you have a specific reason not to.
• Shared config and environment variables can centralize retry policy.
• More retries improve resilience only for transient failures, not permanent ones.