Claude API 529 overloaded_error: meaning and handling

Updated: Oct 24, 2026 · based on the official documentation of Anthropic Claude

529 and 429 are different

429 rate_limit_error means your organization exceeded its limits. 529 overloaded_error means the service is overloaded for everyone, so a higher tier does not help.

How to handle it

Retry with exponential backoff and a cap on attempts; the official SDK retries 5xx twice by default. Keep the request-id header — support needs it.

When streaming, watch for error events in the stream: the HTTP status is already 200 and the error comes later. Do not treat a response as successful by status alone.

Fallback

If the overload lasts, send the request to another model. Through API429 the same key can switch from Claude to GPT or Gemini — only the model field changes.

Retrying with Retry-After: Python example

import email.utils, os, random, time, requests

URL = "https://gateway.api429.com/v1/chat/completions"
HEADERS = {"Authorization": "Bearer " + os.environ["API429_API_KEY"]}
TRANSIENT = {429, 500, 503, 529}

def retry_after(value):
    if not value:
        return None
    if value.isdigit():
        return int(value)
    return max(0, email.utils.parsedate_to_datetime(value).timestamp() - time.time())

def chat(payload, attempts=5):
    for attempt in range(attempts):
        r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
        if r.status_code not in TRANSIENT:
            r.raise_for_status()
            return r.json()
        wait = retry_after(r.headers.get("Retry-After"))
        time.sleep(wait if wait is not None else min(60, 2 ** attempt) + random.random())
    r.raise_for_status()

Frequently asked questions

Did I exceed a limit?

No. 529 means the API is overloaded for all users, not that you exceeded your limits.

How many times should I retry?

A few times with a growing delay. Endless retries add to the load.

Why did the error arrive after 200 OK?

When streaming, the error can come as an error event inside the stream after the status was sent.

What should I keep for support?

The request-id response header.

Sources

platform.claude.com/docs/en/api/errors

Claude API: 529 overloaded_error