Python SDK Retry and Timeout Configuration Reference

Q: 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.

Q: 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.

Q: 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.

Q: 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.

Q: 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.

Q: 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.

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 429 response's retry-after header, 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_retries is 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.

The Anthropic Python SDK Mental Model - how retries and timeouts fit into the client's design
Python SDK Basics - constructing a client with max_retries and timeout
Streaming Responses with the Python SDK - avoiding timeouts on large max_tokens requests
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 anthropic Python 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.

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.

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 429 response's retry-after header, 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_retries is 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 Anthropic Python SDK Mental Model - how retries and timeouts fit into the client's design
Python SDK Basics - constructing a client with max_retries and timeout
Streaming Responses with the Python SDK - avoiding timeouts on large max_tokens requests
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 anthropic Python 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.

Python SDK Retry and Timeout Configuration Reference

Search Documentation

Python SDK Retry and Timeout Configuration Reference