Claude 529 Overloaded: Diagnose the Failure Before Retrying

A Claude 529 overloaded_error means the API is temporarily overloaded. It is not, by itself, evidence that your API key is invalid or your account needs more credits. Anthropic distinguishes overload from authentication, billing, and rate-limit errors in its API error reference.

The useful question is what happened before you received the error. A request rejected before output, a stream interrupted halfway through an answer, and an agent that already changed a file need different recovery decisions. Start there—not with another retry loop.

Start with the product you are using

Where it appears	First useful check
Claude web or mobile app	Save the visible error and time, preserve your prompt and any partial answer, and check the matching component on the Claude status page. A generic “try again” message alone does not identify an HTTP 529.
Claude Code	Identify the session's configured provider. Inspect changed files and completed commands before repeating the task.
Your API integration	Capture the endpoint host, HTTP status, error type, request IDs and retry settings. Use the steps below to separate overload from other failures.

For the web or mobile app, you usually cannot control SDK retry settings. Avoid repeated submissions while an earlier turn is still running. If the failure persists, use the app's support channel with the error and timestamp rather than rotating API keys.

The API details below apply to the direct Claude Messages API unless stated otherwise. Official documentation was checked on November 12, 2026. The recovery examples are simulated; they are not results from a live Tokenhot or Anthropic load test.

1. Identify which service returned the error

Record the destination hostname, requested model, UTC timestamp, HTTP status, and structured error type. For a direct Anthropic request, retain the provider's request-id response header when available. If a gateway sits between your application and Anthropic, keep the gateway request ID separately from any upstream ID it exposes.

For example, a simulated, sanitized non-streaming error record might look like this. The ID is a placeholder, not a support-traceable request:

Endpoint host: api.anthropic.com
HTTP status: 529
Response header request-id: req_REDACTED_EXAMPLE
Response body:
{
  "type": "error",
  "error": {"type": "overloaded_error", "message": "Overloaded"},
  "request_id": "req_REDACTED_EXAMPLE"
}

For a direct response, the header request-id and JSON request_id identify the same request. Keep the original ID in your private incident record and share it with the relevant service's support team when needed. Redact it in public examples; never include an API key or authorization header. Record missing fields as missing rather than inventing an upstream ID.

Do not assume an Anthropic-looking error body proves which hop failed. A gateway can relay an upstream response or use its own error mapping. Ask the gateway operator to trace the request if you cannot establish the origin. This also applies when using Tokenhot; the direct-provider error documentation does not establish Tokenhot's mapping or retry behavior.

Check the Claude status page for an incident matching the affected component and time. Treat that as context, not a verdict on your request. A green status page is not enough reason to discard a reproducible failure.

Use this first decision table:

What you observe	What to do next
Confirmed 529 before any output or tool action	Consider a bounded retry; inspect existing retry layers first.
429 rather than 529	Check rate or spend limits. Waiting cannot fix every 429; use the 429 diagnosis guide.
401 or 402	Investigate authentication or billing respectively; do not run an overload retry loop.
HTTP 200, then an error event or incomplete stream	Mark the attempt incomplete and inspect partial output and actions before replay.
Connection ended without an identifiable overload error	Keep the cause unknown. Start with the timeout and streaming checks.

The table's error meanings follow the direct Claude API. For a proxy or cloud platform, verify its documented error contract before assigning the same meaning.

What if the error appears in Claude Code?

First identify the provider configuration used by that session. Do not treat an error in a coding client as proof that every Claude service is unavailable. Keep the model name, timestamp, and a sanitized error excerpt for the relevant operator.

Before rerunning the task, inspect its work: changed files, executed commands, created resources, and any completed external actions. Restarting a request is not the same as rolling those actions back. A new key or a fresh chat is not a demonstrated fix for a capacity problem.

2. Give retries one owner

Anthropic's official SDK retries eligible transient failures twice by default, and lets you change that behavior with max_retries. Check the Python SDK retry settings for your integration.

Count attempts across the whole path: SDK, application wrapper, worker queue, and gateway if its behavior is documented. For a hypothetical wrapper making three attempts, an SDK making one initial attempt plus two retries can produce up to nine wire attempts, if every failure remains retryable. That is arithmetic, not a measured Tokenhot incident.

Choose one of these designs:

• SDK owns retries: configure its retry allowance, and prevent your wrapper or queue from silently starting another allowance for the same user action.
• Application owns retries: disable SDK retries on that path, then implement the delay, cancellation, attempt limit, and deadline in the application.

Either design needs a total time budget. A retry count alone does not prevent several slow attempts from outliving the user's request. Set per-attempt timeouts within the remaining budget, cancel abandoned work, and stop when the next permitted delay or attempt cannot fit.

When a usable Retry-After is present, respect it. Do not assume every 529 includes one. Without it, use capped exponential backoff with jitter to avoid having all workers retry together. If the requested wait exceeds the job's remaining deadline, defer or fail the job rather than shortening the wait and immediately trying again.

3. Do not replay an interrupted stream as if nothing happened

An HTTP 200 acknowledges the start of a response, not the completion of its content. Claude's streaming documentation describes error events, including overload, and a normal message sequence ending with message_stop.

For a direct Messages stream, distinguish these states:

1. No usable output or action: a retry may be appropriate within the existing budget.
2. Partial text already shown: label it incomplete. If you retry, present a replacement attempt or an explicitly requested continuation; do not silently concatenate the new response with the old one.
3. A tool action may have happened: inspect the application's action record first. A failed model response does not tell you whether a payment, email, file write, or job submission was completed.

Even a normally terminated message may require more work: inspect its stop reason and any tool-use blocks before declaring the user's task complete. Conversely, do not manufacture missing stream events to make a partial response look successful.

For side effects, use your own stable operation identifier and a durable completion record where the downstream system supports that design. Reconcile an uncertain action before executing it again. This is application-level duplicate prevention—not a claim that adding an arbitrary idempotency header makes every model endpoint safe to replay.

Three simulated recovery cases

These examples describe application decisions, not observed incidents or guaranteed provider behavior.

Case A: rejected before the first token. A read-only summary request receives an explicit 529, with no visible output and no tool execution recorded. The SDK has already used its two default retries. The application surfaces a temporary failure when its total attempt budget is exhausted instead of starting three more attempts in a wrapper. If a later user-controlled retry is allowed, it gets a new attempt record linked to the same job.

Case B: text arrives, then the stream fails. A report starts with HTTP 200, emits two paragraphs, and then sends an overloaded_error event without message_stop. Keep the paragraphs marked incomplete. A replacement attempt replaces that partial answer rather than silently appending a second introduction. If the user wants a continuation instead, use the recovery format supported by the selected model: Claude 4.6 and later require a user message asking it to continue rather than an assistant prefill. Preserve necessary context and check the join for omissions or repetition.

Case C: a tool finished before the next model call failed. An agent creates a support ticket, records its ticket ID under a stable application operation ID, and then receives a 529 while preparing the final explanation. Look up that operation and confirm the existing ticket. Resume from its recorded tool result; do not run “create ticket” again. If the tool call timed out and completion is unknown, query the ticket system or reconcile with an operator first. A partial tool-input JSON fragment is not a valid instruction to execute.

4. Make the stop condition explicit

Here is a recovery recipe, not executable code or a tested gateway configuration:

1. Classify the failure and preserve its request identifiers. If it is not a confirmed transient overload, follow the appropriate error path.
2. Check whether the operation completed, produced visible output, or started a side effect. If completion is uncertain, reconcile that state before retrying.
3. Confirm the retry owner, attempts already consumed, cancellation state, and remaining deadline.
4. Retry only when another attempt is allowed and fits the budget. Otherwise return a clear temporary-failure result or defer the job through an explicit queue policy.
5. On success, record completion before acknowledging the job. On another failure, return to the same operation record and budget—not a fresh unlimited loop.

For background work, deferred execution can be more useful than holding a connection open. For an interactive request, a clear failure and a user-controlled retry can be better than a spinner that hides repeated attempts. The right deadline is a product decision; there is no universal waiting period that guarantees capacity returns.

5. Escalate with evidence, not a full prompt dump

If failures persist after the bounded policy, give the service operator a compact incident record:

• UTC timestamps and the affected model and endpoint host.
• HTTP status, structured error type, and provider/gateway request IDs, kept distinct.
• SDK version, configured retry allowance, observed attempts, and whether streaming was enabled.
• Whether output or side effects occurred, plus a minimal sanitized reproduction if one is safe to share.

Exclude API keys, authorization headers, customer data, and unnecessary prompt content. Retain detailed logs securely on your side.

A fallback model or provider is an option only after checking access, request compatibility, output requirements, cost, and data-handling approval. It may share the same underlying bottleneck; switching endpoints is not proof of independent capacity. For the current incident, the goal is simpler: know what failed, avoid multiplying it, and leave the next attempt with an accurate record of what already happened.