Python SDK Retry and Timeout Configuration Reference
This page inferred a generic reference-list layout: it groups the anthropic Python SDK's retry and timeout settings by where they're configured, so you can look up the right knob without re-reading the whole SDK reference.
Every setting shown applies identically to Anthropic() and AsyncAnthropic() unless noted otherwise.
How to Use This Reference
- Start with the Client-level defaults group if you're setting policy for your whole application.
- Use the Per-request overrides group when one specific call needs different behavior than the client's default.
- The What gets retried table tells you which failures the SDK handles automatically, so you don't build redundant retry logic on top of it.
- Revisit this page whenever you add a new call site with unusual latency or reliability requirements (a long-running agent loop, a user-facing request with a tight SLA, and so on).
Client-Level Defaults
Set these when you construct the client. They apply to every request made through that client instance unless overridden per request.
import anthropic
client = anthropic.Anthropic(
max_retries=4, # default is 2
timeout=30.0, # seconds; default is 600.0 (10 minutes)
)| Setting | Type | Default | What it controls |
|---|---|---|---|
max_retries | int | 2 | How many times the SDK automatically retries a request after a retryable failure, before raising an exception. |
timeout | float or httpx.Timeout | 600.0 seconds | The wall-clock ceiling for a single request attempt. Applies per attempt, not to the whole retry sequence. |
base_url | str | https://api.anthropic.com | Not a retry/timeout setting, but commonly set alongside them when routing through a proxy - included here since it's set at the same call site. |
Per-Request Overrides
Use with_options(...) to override a setting for a single call without changing the client's defaults.
# One call needs a tighter timeout and no retries - a latency-sensitive UI request
response = client.with_options(
max_retries=0,
timeout=5.0,
).messages.create(
model="claude-sonnet-5",
max_tokens=200,
messages=[{"role": "user", "content": "Quick classification: is this spam? ..."}],
)| Call shape | Effect |
|---|---|
client.with_options(max_retries=N) | Overrides retry count for calls made on the returned object; the original client is unchanged. |
client.with_options(timeout=N) | Overrides the per-attempt timeout the same way. |
client.with_options(max_retries=N, timeout=N) | Both overrides can be combined in a single call. |
with_options(...) returns a new client-like object; it does not mutate the original client, so the pattern is safe to use inline per call without affecting other code paths sharing the same client.
What Gets Retried Automatically
| Failure | Retried by default? | Why |
|---|---|---|
Network/connection error (APIConnectionError) | Yes | Transient - the request may not have reached the server at all. |
408 Request Timeout | Yes | Transient - the server gave up waiting; safe to try again. |
409 Conflict | Yes | Often transient in the API's usage (e.g. a resource in a temporary state). |
429 Too Many Requests (RateLimitError) | Yes | Transient - back off and retry, honoring retry-after when present. |
5xx server errors | Yes | Transient - a problem on Anthropic's infrastructure, not your request. |
400 Bad Request | No | Non-retryable - the request itself is malformed; retrying reproduces the same error. |
401 Unauthorized | No | Non-retryable - a bad or missing API key won't fix itself on retry. |
404 Not Found | No | Non-retryable - typically an invalid model ID or endpoint. |
Backoff Behavior
- Retries use an increasing delay between attempts (exponential backoff with jitter), not a fixed interval.
- A
429response'sretry-afterheader, when present, is honored as a minimum wait before the next attempt. - The SDK does not expose fine-grained control over the backoff curve itself (base delay, multiplier);
max_retriesis the primary lever you control.
Timeout Granularity
| Concern | Behavior |
|---|---|
What timeout bounds | Each individual HTTP attempt, not the total time across all retries. |
| Worst-case wall-clock time | Can reach roughly timeout × (max_retries + 1) if every attempt times out and is retried. |
| Streaming requests | timeout still applies to establishing the connection and receiving the first bytes; a slow-but-progressing stream is not cut off by the same clock. |
| Passing a plain number | Treated as seconds for both Anthropic() and AsyncAnthropic() - the Python SDK does not use milliseconds. |
Choosing Values for Common Scenarios
| Scenario | Suggested max_retries | Suggested timeout | Reasoning |
|---|---|---|---|
| Interactive, user-facing request | 1-2 | 10-30 seconds | Users notice delay; fail fast and surface an error rather than retrying for a long time. |
| Background batch or ETL job | 4-6 | 60+ seconds | No one is waiting synchronously; favor eventual success over speed. |
Long agentic loop with large max_tokens | Client default (2), combined with streaming | 600 seconds (client default) is usually sufficient once streaming avoids the timeout risk of a single giant non-streaming call | Streaming (see Related) is the primary fix for large-output timeouts, not a larger timeout value alone. |
| Health-check or smoke-test call | 0 | 5-10 seconds | You want to know immediately if something is wrong, not after several retries. |
FAQs
What's the default max_retries if I don't set it?
2.
The SDK retries a transient failure up to two additional times (three attempts total) before raising an exception.
What's the default timeout if I don't set it?
600.0 seconds (10 minutes), applied per attempt.
Does with_options() change the original client?
No.
client.with_options(...) returns a new object with the overrides applied; the original client and its defaults are untouched.
Does timeout apply to the whole retry sequence or just one attempt?
Just one attempt.
If every attempt times out and gets retried, the worst-case wall-clock time can reach roughly timeout × (max_retries + 1).
Will the SDK retry a 400 Bad Request?
No.
400, 401, 403, and 404 are treated as non-retryable, since the request itself (not the network or server) is the problem, and retrying it unchanged would fail again.
Is retry/timeout configuration different between Anthropic() and AsyncAnthropic()?
No.
Both client classes accept the same max_retries and timeout constructor arguments and support the same with_options(...) pattern.
Does a 429 response respect the API's retry-after header?
Yes.
When the response includes a retry-after header, the SDK honors it as a minimum delay before the next retry attempt.
Should I set max_retries to 0 for a health check?
That's a reasonable choice.
A health check usually wants to know immediately whether the API is reachable, rather than masking a real outage behind several retry attempts.
Can I set a different timeout for streaming vs non-streaming calls?
Yes, using the same with_options(timeout=...) pattern per call, or by setting different timeouts on separate client instances if the split is consistent across your application.
Does raising max_retries fix a slow response that eventually succeeds?
Not directly.
max_retries addresses failures, not slowness; a request that succeeds but is simply slow is a timeout concern, and for large outputs, switching to streaming is usually the better fix.
What exception do I catch if retries are exhausted?
The typed exception matching the underlying failure - for example anthropic.RateLimitError for exhausted 429 retries, or anthropic.APIConnectionError for exhausted network-error retries. See the exception reference page for the full mapping.
Related
- The Anthropic Python SDK Mental Model - how retries and timeouts fit into the client's design
- Python SDK Basics - constructing a client with
max_retriesandtimeout - Streaming Responses with the Python SDK - avoiding timeouts on large
max_tokensrequests - Python SDK Exception Types at a Glance - what to catch when retries are exhausted
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official
anthropicPython SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.