Errore Claude 529 overloaded_error: cause e gestione

Il 529 è l’unico errore di Claude che il mio codice non ha causato. Il sovraccarico riguarda Anthropic e non c’è nulla che io possa correggere. Posso solo gestirlo correttamente: retry pazienti con backoff, un modello di fallback per i percorsi sensibili alla latenza e nessuna raffica di retry immediati che aggravi l’incidente.

L’errore

Risposta (HTTP 529)

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

Cause e soluzioni in breve

Causa	Soluzione
Sovraccarico lato provider (giorni di lancio di nuovi modelli, incidenti regionali). Si verifica contemporaneamente per tutti i clienti.	Aspetta usando backoff con jitter. Non ridistribuire l’app e controlla la pagina di stato di Anthropic.
Il mio traffico burst coincide con una capacità già al limite.	Distribuisci nel tempo i processi batch. Un ritardo di soli 10 minuti di solito risolve il problema.
Confusione con il 429. Nei log possono sembrare simili, ma la causa è completamente diversa.	Il 429 indica che ho superato il mio limite (il server è normale); il 529 indica che il server è sovraccarico (limite e saldo sono normali). Solo il 429 include l’indicazione Retry-After.
Non è definito alcun fallback, quindi il problema del provider arriva direttamente all’utente finale.	Definisci una sequenza di fallback. Restando nella stessa famiglia (Sonnet → Haiku), il comportamento è simile; passando da un provider all’altro (Claude → GPT), puoi superare anche un’interruzione completa.

Creare retry che non aggravino l’incidente

Tratta il 529 come un “429 senza Retry-After”. Backoff esponenziale a partire da circa 2 secondi, jitter, limite superiore di 30–60 secondi, poi arrenditi dopo circa cinque tentativi e inserisci il lavoro in coda. Il punto fondamentale è il jitter: senza jitter, tutti i client tornano nello stesso momento e prolungano proprio il sovraccarico dal quale stavano cercando di uscire.

Passare oltre invece di interrompere

Definisci una catena di fallback per i percorsi sensibili alla latenza. Se l’endpoint è compatibile con OpenAI, devi cambiare solo una stringa: non servono un nuovo SDK né un nuovo account:

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          # 과부하 — 다음 후보로
    raise last

Mettere in dubbio il mio codice viene per ultimo

Se il 529 compare solo per determinati tipi di richieste mentre altre chiamate nello stesso momento passano, non si tratta di un’interruzione completa. Verifica se quel percorso invia prompt insolitamente grandi o effettua chiamate consecutive in un ciclo stretto. Al contrario, se tutte le chiamate diventano 529 contemporaneamente e poi il problema si risolve da solo, la causa è la capacità. In quel caso devi intervenire su retry e fallback, non fare refactoring.

Se chiami tramite Kunavo

Kunavo instrada Claude attraverso più percorsi upstream e, grazie al catalogo multimodello, il fallback tra provider consiste nel “cambiare solo il nome del modello, con la stessa chiave e lo stesso saldo”. Il codice sopra non richiede un secondo account. Inoltre, i 529 che raggiungono Kunavo non vengono addebitati. Capacità e prezzo sono domande separate. Per la seconda, le tariffe per modello sono riportate nella tabella dei prezzi dell’API Claude.

Domande frequenti

Il 529 è colpa mia?

No. È un problema di capacità lato provider. Le uniche responsabilità sono due: non amplificare l’incidente (backoff e jitter) e predisporre un percorso alternativo quando l’incidente dura più a lungo della latenza massima consentita.

Qual è la differenza tra 529 e 429?

Il 429 indica che ho superato il mio limite mentre il server è normale. Il 529 indica che il server è sovraccarico mentre il mio limite è normale. Entrambi sono soggetti a retry, ma solo il 429 include l’indicazione Retry-After.

Quanto dura di solito lo stato 529?

Non è prevedibile né garantibile. Per questo la risposta corretta è un backoff con limite superiore e una coda, non un tempo di attesa fisso inserito nel codice. Se il percorso ha una soglia di latenza, il fallback subentra invece di aspettare.

Le chiamate fallite con 529 vengono addebitate?

Passando da Kunavo, no. Le richieste che terminano con un errore non vengono fatturate. Con un contratto diretto, valgono le regole di fatturazione del singolo provider.

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.

Errore Claude API 529 overloaded_error — cosa significa e come superarlo