Errore Claude API 529 overloaded_error — cos’è e come superarlo

Il 529 è l’unico errore di Claude che il tuo codice non ha causato: Anthropic è sovraccarica. Non puoi correggerlo, puoi solo assorbirlo correttamente. Questo significa retry pazienti, un modello di fallback e nessuna raffica di retry immediati che amplifichi l’incidente.

L’errore

risposta (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

Cause e soluzioni in breve

Causa	Soluzione
Saturazione lato provider (giorni di lancio, incidenti regionali)	Usa il backoff con jitter; controlla la pagina di stato del provider invece di ridistribuire l’app.
Il tuo burst arriva durante un incidente circoscritto	Distribuisci i processi batch; un ritardo di 10 minuti di solito risolve il problema.

Riprovare con criterio

Tratta il 529 come un 429 senza Retry-After: backoff esponenziale a partire da circa 2 s, jitter, limite di 30–60 s, rinuncia dopo circa 5 tentativi e metti il lavoro in coda. Lo snippet di backoff della nostra guida al 429 gestisce il 529 nello stesso ramo.

Fare failover invece di fallire

Per i percorsi sensibili alla latenza, definisci un fallback: la stessa famiglia (Sonnet → Haiku) mantiene il comportamento simile; il passaggio tra provider (Claude → GPT) sopravvive a un incidente dell’intero provider. Su un endpoint compatibile con OpenAI è sufficiente cambiare una stringa:

failover.py

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # saturated — try the next tier
    raise last

Se chiami tramite Kunavo

Kunavo instrada Claude attraverso più percorsi upstream e il suo catalogo multimodello rende il failover tra provider una modifica della stringa del modello, con la stessa chiave e lo stesso portafoglio; il pattern di failover sopra non richiede un secondo account. I 529 che ti raggiungono non vengono comunque mai addebitati. Capacità e prezzo sono domande separate; per la seconda, le tariffe per modello sono nella tabella dei prezzi dell’API Claude di Anthropic.

Domande frequenti

Il 529 è colpa mia?

No. È un problema di capacità lato provider. Le tue uniche responsabilità sono non amplificarlo (backoff e jitter) e avere un percorso di failover se l’incidente supera il tuo budget di latenza.

529 e 429: qual è la differenza?

Il 429 indica che hai superato i tuoi limiti (il server funziona); il 529 indica che il server stesso è sovraccarico (la tua quota è normale). Entrambi consentono il retry; solo il 429 include un’indicazione retry-after.

Guide correlate

Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.