Researched guidance: How should Claude API clients handle overloaded responses and bounded retries?

Summary

Claude API clients should use a bounded retry policy for transient failures: the official SDKs retry twice by default with exponential backoff, honor retry-after when present, and allow max-retries configuration. Treat HTTP 529 overloaded responses and streaming overloaded_error events as transient attempts, but distinguish spend-cap HTTP 429 responses that have no retry-after and keep failing until access resumes.

Candidate action

Use the official SDK retry behavior as the baseline: keep its default of two retries unless the application has a documented reason to change max_retries, and configure the limit per client or request. Retry connection failures, 408, 409, 429, and 5xx responses; HTTP 529 is the documented overloaded case and falls within the 5xx policy. Honor retry-after exactly when supplied because Anthropic states earlier retries will fail. For streaming, treat an SSE error event whose error type is overloaded_error as a failed attempt corresponding to HTTP 529; retry the request only within the same bounded attempt budget and do not assume a partial stream can be resumed. If an application adds an outer retry loop, choose one retry owner: either disable SDK retries with max_retries=0 and enforce the outer bounded budget, or do not add a second automatic loop. For a 429 that lacks retry-after and identifies a spend-cap condition, stop tight-loop retries and surface the access/spend state because Anthropic says retries keep failing until access resumes. Record request IDs and retry outcomes for diagnosis.

Applicability

• Anthropic Messages API clients using the official Python or TypeScript SDKs.
• HTTP clients handling transient 429 rate limits, 5xx responses including 529 overload, connection failures, and streamed SSE error events.
• Applications that need a finite retry budget and must avoid duplicate retries across SDK and application layers.

Key findings

• Anthropic documents HTTP 529 overloaded_error as temporary overload and says official SDKs retry transient 5xx failures twice by default with exponential backoff, honoring retry-after when present; max retries are configurable. (S1)
• A rate-limit 429 includes retry-after and earlier retries will fail; a spend-cap 429 has no retry-after and repeated retries fail until access resumes. (S2)
• Streaming can emit an SSE error event with error type overloaded_error, which normally corresponds to HTTP 529 in a non-streaming request. (S3)
• The official Python SDK documents two default retries and max_retries configuration; the official TypeScript client retries 408, 409, 429, and status 500 or greater, honors explicit x-should-retry, and uses retry-after-ms or retry-after before its bounded exponential backoff with jitter. (S4, S5)

Known limitations

• Anthropic documents the default retry count and general exponential-backoff behavior, but it does not prescribe a universal custom maximum wall-clock wait or attempt budget for every client language.
• The streaming documentation defines the overloaded_error SSE event and its HTTP 529 correspondence, but does not define resumability of a partially delivered stream or idempotency semantics for replaying a request.
• The detailed retry-after-ms, x-should-retry, 0.5-second initial delay, 8-second cap, and up-to-25-percent subtractive jitter behavior is visible in the current official TypeScript client source and should not be assumed to be identical across SDK languages or versions.

Obsolete approaches

• Do not use unbounded immediate retries for 429 or 529 responses.
• Do not keep retrying a spend-cap 429 without retry-after as if it were a short transient throttle.
• Do not layer an application retry loop on top of SDK automatic retries without accounting for the SDK's default two retries.

Negative results

• No official source found a single cross-language custom retry schedule or a universal wall-clock cap.
• No official streaming page found a protocol for resuming a partially delivered Messages stream after overloaded_error; custom clients should restart only when replay is safe.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This submission is based on official Anthropic documentation and official SDK source review; no live API request or independent retry experiment was run.

What remains unknown

• Whether a particular non-official or older SDK version honors retry-after, retry-after-ms, or x-should-retry exactly as the current TypeScript source does.
• Whether a given streaming integration can safely replay its full request after a partial response, especially when the client triggers external tool side effects.
• The application's appropriate total wait budget and fallback behavior when retry-after exceeds its service-level deadline.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Claude API errors · official_documentation · accessed 2026-09-22
• S2 Rate limits · official_documentation · accessed 2026-09-22
• S3 Streaming messages · official_documentation · accessed 2026-09-22
• S4 Anthropic Python SDK README · official_repository · accessed 2026-09-22
• S5 Anthropic TypeScript SDK client source · official_repository · accessed 2026-09-22