Claude Code 529 Overloaded: Causes, Retry Settings and Fixes

Wokey Team · 2026-09-24

Short answer: a 529 means the upstream model is out of capacity right now ("overloaded"). It has nothing to do with your balance, your quota or your API key. Claude Code has already retried several times before it shows the error. The fastest fix is to switch models with /model, because capacity is tracked per model. If you're not in a hurry, wait a few minutes and send again.

The exact error

In Claude Code you see:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Claude Code's documentation makes three points about it:

• It is temporary capacity trouble shared by all users.
• Claude Code has retried several times before showing it.
• A 529 is not your usage limit and doesn't count against your quota.

When you connect through a gateway with ANTHROPIC_BASE_URL, the last sentence names the gateway host instead of status.claude.com.

Where a 529 comes from on Wokey

Wokey never produces a 529 itself; the status always comes from the upstream model. Wokey handles it in three steps:

1. When the upstream reports overload (for example Anthropic's overloaded_error), Wokey first retries your request on another upstream route for the same model. You don't see this.

2. Only if the retry is overloaded as well does Wokey pass the upstream status through. The HTTP status stays 529. The body uses Wokey's standard error format, with the upstream's own wording in message:

   {"error":{"code":"upstream_unavailable","message":"Overloaded","type":"invalid_request_error"}}
   

3. If the overload happens after the reply has started streaming, it arrives as an in-stream error event rather than an HTTP 529.

So a 529 through Wokey means several upstream routes for the same model were overloaded at once, usually during a peak on the provider's side. These responses carry no Retry-After header; your client retries on its own backoff schedule.

Telling it apart from other errors

Only 529 and 503 mean "the upstream is busy". The others need action on your side.

What to do

1. Wait and resend. Overload usually clears within minutes, and Claude Code's automatic retries already cover short spikes.

2. Switch models with /model. Capacity is tracked per model, so when Opus is overloaded Sonnet often still works. Run /model in the session and pick another model; there's no need to restart.

3. For unattended long jobs, retry harder. Add this to the env block of ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1 makes Claude Code retry 429 and 529 errors indefinitely, backing off up to 5 minutes between attempts. It suits jobs left running overnight.
• For just a few more attempts, set CLAUDE_CODE_MAX_RETRIES instead. It defaults to 10 and is capped at 15.

4. In your own code, leave room to retry 529s. The official Anthropic SDKs retry 5xx errors, 529 included, twice by default. For batch jobs, raise max_retries and add exponential backoff around the call.

Seeing a 529 in Codex

Codex treats 5xx errors, 529 included, as retryable:

• The HTTP layer retries 4 times by default (the provider's request_max_retries).
• The stream layer then retries up to 5 more times (stream_max_retries).
• If all of those fail, the error starts with unexpected status 529, followed by the response body.

A code of upstream_unavailable in that body means the upstream overload described above. The fix is the same: wait, or switch models in config.toml. For the full Codex setup see the Codex config.toml guide.