Claude 529 overloaded error: what it means and how to handle it

The claude overloaded 529 error is alarming because it shows up suddenly, mid-task: the agent stops, the script crashes. The good news is that your key and balance are fine; it's overload on the API side. Below: what Anthropic's docs say about it, how to retry, when to switch to a fallback model, and what it looks like when you work through the Zukko gateway.

What claude overloaded 529 means

Anthropic's docs describe code 529 with type overloaded_error like this: the API is temporarily overloaded. They add that 529 occurs when there's high traffic across all users. The error body has the same shape as other API errors:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "..."
  },
  "request_id": "req_..."
}

request_id is useful if you contact support. In streaming, the error can arrive after a 200 response, as a separate event inside the stream, so handle errors there too.

Don't confuse 529 with neighboring codes:

One caveat from the same docs: if your traffic spikes sharply, you may get a 429 from acceleration limits rather than a 529. Anthropic's advice is to ramp up load gradually.

In Claude Code this error looks like API Error: Repeated 529 Overloaded errors, shown after Claude Code has already retried the request several times on its own. The Claude Code docs state plainly that a 529 is not your usage limit and doesn't count against your quota.

What to do: retry with backoff

Overload is usually temporary, so the first remedy is to retry, but sensibly:

1. Exponential backoff with jitter. 1, 2, 4 seconds plus a random fraction of a second, so your workers don't hit the API all at once.
2. The retry-after header. If it arrives, wait at least that long.
3. A limited number of attempts. Two or three per model, then a fallback model or an error up the stack.
4. Don't double up on retries. The official Anthropic SDK already retries transient errors, including 5xx, twice by default (the max_retries parameter). If you write your own loop, turn the built-in one off, or you'll get three times as many attempts. In the Python SDK, a 529 surfaces as the anthropic.OverloadedError exception.

In Claude Code, the number of automatic retries is set by the CLAUDE_CODE_MAX_RETRIES variable (10 by default).

Fallback model

If retries don't help, switch to another model. The Claude Code docs explain why this works: capacity is tracked per model, and one model being overloaded doesn't mean another one is.

An example chain and its cost per 1,000 requests at 2,000 input and 500 output tokens (prices as of October 7, 2026; formula 1000 × (2000 × input + 500 × output) / 1,000,000):

The intelligence index is the Artificial Analysis Intelligence Index from the Zukko catalog. Checking a row: for Opus 5.5, 2 × 0.8 + 0.5 × 4 = 1.6 + 2 = $3.60. A model from another vendor at the end of the chain covers the case when the whole provider has problems. Before putting a fallback into production, run 20–30 typical requests on it: does it keep the response format your code expects?

Two practical details. The fallback model has its own cache, so the first request after a switch goes without cache reads. And if the key has allowed_models set, add the fallback models there, or you'll get a 403 instead of an answer. For the current list and prices, call GET https://api.zukko.pro/v1/models or open the Models page in the dashboard.

Fallback model in Claude Code

Claude Code has a --fallback-model flag: when the primary model is overloaded or unavailable, it switches the current turn to the fallback. You can list up to three models separated by commas, and for a permanent setup there's the fallbackModel array in settings.json:

claude --fallback-model claude-sonnet-5

According to the docs, the switch lasts for the current turn only; your next message goes to the primary model again. Authentication, billing, and rate-limit errors don't trigger the fallback. To change models by hand, use /model. Setting up Claude Code with Zukko is covered in the Claude Code docs↗; remember to set ANTHROPIC_DEFAULT_HAIKU_MODEL to a catalog model, or background requests go to claude-haiku-* and get 404 model_not_found.

What overload looks like through Zukko

When you work through the gateway, provider overload can arrive as a 529 (the gateway passes the provider's status through) or as a 503 — handle both the same way. Codes worth telling apart:

Zukko has no general rate limit of its own. To keep your code robust regardless of the request path, treat 529 and 503 (without model_disabled) the same way, as temporary overload. More on 503 in the article on an unavailable provider↗.

Code: retries and fallback with the Anthropic SDK

Through Zukko, any model can be called in any format, so a GPT model fits into an Anthropic SDK chain just fine — the gateway converts the request:

import random
import time

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.zukko.pro",
    api_key="fetch_your_key",
    max_retries=0,  # we handle retries ourselves
)

CHAIN = ["claude-opus-5-5", "claude-sonnet-5", "gpt-6.1-sol"]
RETRYABLE = {429, 500, 502, 503, 504, 529}
KEY_LIMITS = {"key_daily_limit_reached", "key_monthly_limit_reached"}

The code retries only on transient errors, including 529 and 503, and stops immediately on a key limit, insufficient balance, or a request error: neither a pause nor another model will fix those. Endpoint reference in the /v1/messages docs↗; a version of the same approach on the OpenAI SDK is in the article on retries for 503↗.

If you want fallback models available on the same key without separate accounts at each vendor, create a key in the dashboard and add the chain to allowed_models.

FAQ

Is a 529 my limit?

No. According to Anthropic's docs, it's API overload across all users. Your limit is a 429 rate_limit_error. A similar mix-up on the OpenAI side is covered in the article the insufficient_quota error↗.

How long should I wait if 529 keeps happening?

Overload is usually temporary. Make two or three attempts with growing pauses, then switch to a fallback model. Anthropic publishes service status at status.claude.com.

Why do I sometimes see 503 instead of 529 through Zukko?

Provider overload can come through the gateway as a 529, because the gateway passes the provider's status through, or as a 503, which is how Zukko reports an unavailable provider. Treat 529 and 503 the same way, as in the code above, and your code will work whatever path the request takes.

Will switching models help?

Yes, capacity is tracked per model. The most reliable fallback is a model from another vendor that you've tested on your requests in advance.