Anthropic Error: overloaded_error — API Overloaded

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}],
    )
except anthropic.APIStatusError as e:
    # e.status_code == 529
    # e.body['error']['type'] == 'overloaded_error'
    # e.body['error']['message'] == 'Overloaded'
    if e.status_code == 529:
        # transient — retry with backoff
        ...

overloaded_error is Anthropic’s signal that the Claude inference fleet is at capacity for the model you asked for. It returns HTTP 529 — a non-standard status code Anthropic shares with a handful of other services to mean specifically “we’re hot, slow down or come back.” It’s not a rate limit (which is 429) and it’s not a generic server error (which is 500); it’s a capacity signal you should react to with retry and fallback, not reconfiguration.

The right response is mechanical: bounded exponential backoff with jitter, then a fallback to a smaller-fleet model (Haiku) or an alternate provider (Bedrock, Vertex), then a circuit-break that gives up cleanly. Combined with a status-page subscription and per-model 529 metrics, you can keep serving traffic through capacity events that take competitors offline.

Why this happens

• Cluster-wide capacity event at Anthropic. The most common cause — Anthropic's GPU/inference fleet for the requested model is saturated. Major causes include traffic spikes from a viral product (cursor, claude.ai outage), a model release attracting load, or a regional infra incident. status.anthropic.com tracks these as 'partial outage' or 'degraded performance' events.
• Specific model under heavier load than others. Newer flagship models (Opus, the latest Sonnet) get hit hardest after release. Older or smaller models in the same family may have more headroom. Routing some traffic to Haiku or an older Sonnet snapshot during overloads keeps you serving.
• Regional or availability-zone issue. Anthropic runs across multiple regions; a localised hardware fault can drop capacity in one zone while others are healthy. AWS Bedrock and GCP Vertex routes to Claude have their own zone exposure separate from the direct Anthropic API.
• Burst from your own traffic colliding with global load. If you fan out 1,000 concurrent calls just as another large customer also bursts, Anthropic's per-region scheduler can shed load with `overloaded_error` rather than queue indefinitely. Smoothing your own bursts (token bucket, queue) reduces collision probability.
• Free-tier or low-tier deprioritisation during contention. Anthropic prioritises higher-tier paid traffic during capacity events. Free-trial keys and tier-1 paid orgs see `overloaded_error` more often than tier-3+ enterprise traffic when global demand peaks. Upgrading via spend reduces — but doesn't eliminate — the rate.

How to fix it

Fixes are ordered by likelihood. Start with the first one that matches your context.

import time, random
import anthropic

client = anthropic.Anthropic()

def call_with_retry(messages, model="claude-opus-4-5", max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return client.messages.create(
                model=model, max_tokens=1024, messages=messages,
            )
        except anthropic.APIStatusError as e:
            if e.status_code != 529 or attempt == max_attempts - 1:
                raise
            backoff = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(min(backoff, 30))

FALLBACK = ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"]

def call_with_fallback(messages, max_tokens=1024):
    last_err = None
    for model in FALLBACK:
        try:
            return client.messages.create(
                model=model, max_tokens=max_tokens, messages=messages,
            )
        except anthropic.APIStatusError as e:
            if e.status_code != 529:
                raise
            last_err = e
    raise last_err

Detection and monitoring in production

Track `overloaded_error` rate per model as a separate metric from rate-limits. Plot it against status.anthropic.com incidents to correlate. Alert if 529s exceed 5% of requests for a single model over a 5-minute window — that's a signal to flip your traffic over to the fallback model or a different provider. A sustained 0% rate at scale is unrealistic; aim for <1%.