Claude 529 Overloaded: Diagnose It Without Starting a Retry Storm

A Claude 529 overloaded_error means the direct Anthropic API is temporarily overloaded. It is a transient server-capacity signal—not, by itself, evidence that your API key was banned, your account ran out of credit, or you exceeded a normal rate limit.

The safe first move is not “retry harder.” Before another attempt, save the exact error body, timestamp and time zone, client surface, provider, model, request_id, any partial output or completed tool action, and how many retries may already have happened. Then check the status page for the provider you actually used and allow one retry owner to apply bounded backoff.

The two-minute triage

Use this sequence before changing code or repeatedly pressing Retry:

1. Preserve the failure. Copy the full status code, error type, message, response headers, request ID, timestamp, model, endpoint and client version.
2. Name the surface. Was it the direct Anthropic API, Claude Code, claude.ai, Amazon Bedrock, Google Vertex AI, or a third-party gateway or automation?
3. Check for partial completion. Save streamed text. Verify whether a tool call, database write, email, payment, deployment or other side effect already occurred.
4. Count the retry layers. Your SDK, CLI, application, job runner, gateway and platform may each retry independently.
5. Check the matching provider status. A green aggregate dashboard is useful context, but it does not disprove a short-lived, model-, route-, region-, account- or gateway-specific failure.
6. Choose one bounded next action. Wait and retry through a single layer, switch models only if your route and task allow it, queue the job for later, or escalate with correlated evidence.

If the operation can create an external side effect and you cannot prove whether it completed, stop automatic retries until you reconcile that side effect.

First, confirm that the error is really a 529

Anthropic's API error reference distinguishes 529 overloaded_error from 429 rate_limit_error. The returned HTTP status and structured error type matter more than a UI toast or a gateway's rewritten message.

A client or intermediary may wrap the upstream response. If all you have is the text “Claude is overloaded,” retrieve the raw response and identify which provider issued it before applying Anthropic-specific behavior. A 529 seen through a gateway is not enough to infer the gateway's retry, billing or idempotency rules.

The correct recovery depends on where you saw it

Direct Anthropic API

For a direct API call, preserve the request_id from the error body or request-id response header. Anthropic says its official SDKs retry eligible transient failures—including connection errors, 429 responses and 5xx responses—twice by default with exponential backoff, and honor retry-after when it is present.

That default matters: if your application adds three attempts around an SDK that already performs retries, the number of actual requests can be greater than the loop count suggests. Inspect the SDK version and retry configuration before adding another wrapper.

Use bounded retries only when the operation is safe to repeat. Add jitter, cap concurrency, and stop after a defined attempt or time budget. For asynchronous workloads, moving the request back to a queue is usually safer than keeping many workers in synchronized retry loops.

Claude Code

Claude Code has its own behavior. Anthropic's Claude Code error guide says eligible transient failures are retried up to 10 times with exponential backoff before an error is shown. Therefore, a displayed “Repeated 529” is not the first attempt; the client has already retried several times.

The same guide says Claude Code does not rerun a mid-stream failure after a completed text block or tool call, because replaying it could execute the tool call twice. Preserve the completed work and inspect the repository, terminal and external system state before starting the prompt again.

Anthropic documents repeated Claude Code 529 as a capacity error rather than a usage limit and says it does not count against Claude Code quota. That statement is specific to Claude Code. It is not a promise that a direct API request or third-party gateway attempt is unbilled.

Claude Code can also be routed through another provider. Check the provider named in the error and its status page; do not assume every Claude Code 529 came directly from Anthropic.

claude.ai

In claude.ai, save the conversation URL, timestamp, model selection, visible error and any text that arrived before the failure. Check Claude's public status page, then wait before a manual retry. If the conversation contains a file upload, connector action or artifact you care about, verify what was retained before resubmitting.

The browser UI may not expose the same diagnostic fields as an API response. Do not manufacture a request ID or conclude that the cause is identical to a direct API 529.

Bedrock, Vertex AI or a third-party gateway

Treat the intermediary as a separate system boundary. Capture both its request ID and any upstream Anthropic ID it exposes. Check its status, retry configuration, timeout, model mapping, usage records and error translation.

The gateway may retry upstream calls, replace status codes or return an error after its own timeout. Follow the intermediary's documentation for billing and replay behavior; Anthropic's direct API documentation cannot establish those facts for another platform.

Make one layer own the retry policy

Start by writing down every possible attempt source:

Choose one layer as the retry owner. Disable or tightly limit overlapping layers where possible. The owner should enforce:

• a maximum attempt count and total elapsed-time budget;
• exponential backoff with jitter;
• concurrency limits so recovery traffic does not amplify overload;
• cancellation when the user abandons or supersedes the request;
• durable correlation IDs and attempt logs;
• an idempotency or reconciliation strategy for side effects;
• a terminal state that goes to a queue, fallback or human review instead of looping forever.

Anthropic documents CLAUDE_CODE_RETRY_WATCHDOG=1 for unattended Claude Code sessions: it can retry 429 and 529 capacity errors indefinitely and raises the retry count for other transient errors to 300, roughly three hours of backoff. That is an operational mode, not a harmless universal fix. Use it only with explicit concurrency, budget, idempotency and stop controls.

A conservative retry pattern

The following TypeScript-shaped pseudocode makes the application the retry owner. Adapt it to your SDK's actual API, and either disable SDK retries or include them in the total attempt budget.

ts
const policy = {
  maxAttempts: 3,
  maxElapsedMs: 90_000,
  baseDelayMs: 1_000,
};

async function runClaudeJob(job: Job) {
  const startedAt = Date.now();

  for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
    try {
      return await sendOnce(job); // Configure nested SDK retries deliberately.
    } catch (error) {
      recordAttempt({
        jobId: job.id,
        attempt,
        status: error.status,
        type: error.type,
        requestId: error.requestId,
        partialOutput: error.partialOutput,
      });

      const isOverload =
        error.status === 529 && error.type === "overloaded_error";
      const uncertainSideEffect = await needsReconciliation(job, error);
      const budgetExpired = Date.now() - startedAt >= policy.maxElapsedMs;

      if (!isOverload || uncertainSideEffect || budgetExpired) throw error;
      if (attempt === policy.maxAttempts) throw error;

      await sleep(withJitter(policy.baseDelayMs * 2 ** (attempt - 1)));
    }
  }
}

This is a control pattern, not a provider guarantee. It deliberately avoids prescribing a universal wait time because the correct budget depends on latency objectives, queue capacity, operation safety and the retry behavior already present below your code.

Streaming failures need a different decision

Anthropic notes that an SSE stream can emit an error after the initial HTTP response was 200. In that case, “the request succeeded” and “the operation failed” are both oversimplifications: some text may have arrived, and a tool action may already have completed.

Before replaying:

1. Save every completed stream event and the final error event.
2. Record the request_id and your own correlation ID.
3. Identify the last completed text block or tool call.
4. Reconcile external side effects from logs or the target system.
5. Decide whether to continue from saved state, submit a reduced follow-up, or restart only after proving a replay is safe.

For write operations, use application-level idempotency keys or a durable operation record where the target system supports them. Do not claim a retry is duplicate-safe merely because the first client call ended with an error.

What a green status page does—and does not—mean

A public status page is an aggregate operational view. It can confirm a known broad incident, but an “operational” state cannot rule out:

• a brief event that has not yet been posted;
• capacity pressure on one model;
• a provider-, route- or region-specific problem;
• an account- or workspace-specific condition;
• a third-party gateway failure;
• an individual request or streaming failure.

Record the status-page state and the time you checked it. If failures persist, compare a minimal safe request across an allowed model or route—but change one variable at a time. Otherwise, a simultaneous model, provider and client change destroys the evidence needed to identify what recovered.

When model switching is reasonable

Claude Code's error guide notes that capacity is tracked per model, so switching models can be a documented recovery option there. Consider it only when:

• the alternate model is available through your actual provider and account;
• its capabilities and context limits fit the task;
• policy, data residency and cost constraints allow the switch;
• the operation can be safely restarted;
• you label or log the model change so outputs remain traceable.

Do not use a model switch to bypass an unresolved side effect or to obscure a persistent route failure.

Build an escalation packet instead of sending “Claude is down”

If bounded recovery fails, send support or your platform team a compact, correlatable packet:

json
{
  "observed_at": "2026-08-21T15:42:18Z",
  "surface": "direct Anthropic API | Claude Code | claude.ai | gateway",
  "provider": "Anthropic | Bedrock | Vertex AI | other",
  "model": "exact model identifier",
  "http_status": 529,
  "error_type": "overloaded_error",
  "request_id": "request ID, if exposed",
  "client_and_version": "SDK, CLI, browser, integration",
  "retry_layers": ["SDK: 2 default retries", "application: disabled"],
  "attempts_and_timing": "timestamps and backoff for each attempt",
  "stream_state": "none | partial text | completed tool call",
  "side_effect_state": "not started | confirmed complete | uncertain",
  "status_page_checked_at": "timestamp and provider status",
  "usage_record_checked": "yes | no | unavailable"
}

Remove secrets, prompts and customer data that support does not need. Keep the original error tokens unchanged so the report can be matched to logs.

Billing and duplicate-work questions require evidence

The fact that a client displayed 529 does not establish whether an individual attempt was billed, completed upstream, or safe to replay. The public API error documentation does not provide a universal billing or idempotency rule for every 529, timeout or mid-stream failure. Third-party platforms add their own contracts and records.

To resolve a specific case, correlate:

• upstream and gateway request IDs;
• API or workspace usage records;
• gateway billing records;
• client and worker logs;
• stream events and stored output;
• tool, database and external-system audit logs;
• retry configuration at every layer.

If those records disagree, preserve them and escalate. Do not turn uncertainty into a “failed requests are free” or “every retry is charged” rule.

Frequently asked questions

Is Claude error 529 a ban?

No conclusion about a ban follows from 529 alone. Anthropic defines direct-API 529 overloaded_error as temporary overload. Authentication and authorization problems use different error categories. Confirm the raw response because a client or gateway may rewrite messages.

Is 529 the same as a rate limit?

No. Anthropic distinguishes 529 overload from 429 rate limits. A 429 can involve rate, acceleration, spend-cap or Claude Code workspace constraints; inspect the exact error and headers rather than treating both as generic capacity failures.

How long should I wait before retrying?

There is no evidence-backed universal 529 wait time. Honor retry-after when present, otherwise use bounded exponential backoff with jitter under one retry owner. Include attempts already made by the SDK, CLI or gateway in your budget.

Why do I still get 529 when the status page is green?

The dashboard is an aggregate snapshot, not a diagnosis for one request. A brief, model-, route-, account-, region- or gateway-specific problem may not appear as a broad incident. Preserve the request evidence and check the provider actually serving your call.

Should I keep retrying Claude Code?

If Claude Code shows repeated 529, it has already retried several times. Check the named provider status, protect completed tool work, and consider an allowed model switch or a later retry. Do not add an outer infinite loop without explicit safety controls.

Can I assume a failed attempt was not billed?

No. A 529 display alone cannot establish billing, completion or duplicate safety for a particular direct API or intermediary request. Use correlated usage, request and platform records.

The recovery rule to keep

Treat 529 as a transient overload signal, but treat replay safety as a separate question. Identify the real surface, preserve the original evidence, account for retries that already happened, and let one bounded policy own the next attempt. When completion or side effects are ambiguous, reconciliation comes before retry.