Errore Claude 529 overloaded_error — causa e strategia di ritentativo

529 è l'unico errore di Claude che il tuo codice non ha provocato: il sovraccarico è di Anthropic. Non puoi risolverlo — puoi solo assorbirlo con eleganza. Ciò significa ritentativi pazienti con backoff, un modello di riserva nei percorsi sensibili alla latenza e, soprattutto, niente raffiche di ritentativi immediati che amplificano 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, incidenti regionali). Colpisce tutti i clienti contemporaneamente.	Backoff con jitter; consulta la pagina di stato di Anthropic invece di ridistribuire l'applicazione.
Il tuo picco di carico si somma a una capacità già sotto pressione.	Distribuisci i lavori in batch; un ritardo di dieci minuti spesso risolve il problema.
Confusione con 429: nei log un limite di frequenza può sembrare uguale, ma la causa è completamente diversa.	429 significa che hai superato i tuoi limiti (il server funziona correttamente); 529 significa che il server è sovraccarico (la tua quota è corretta). Solo 429 include l'indicazione Retry-After.
Non è definita alcuna riserva, quindi un problema del provider raggiunge l'utente finale.	Definisci una catena di riserva — all'interno della stessa famiglia (Sonnet → Haiku) il comportamento resta simile; tra provider (Claude → GPT) sopravvivi a un incidente completo.

Ritentare senza amplificare l'incidente

Tratta 529 come un 429 senza Retry-After: backoff esponenziale a partire da circa 2 secondi, con jitter, limite massimo di 30–60 secondi, rinuncia dopo circa cinque tentativi e accoda il lavoro. Il jitter è la parte importante: senza di esso tutti i clienti ritentano contemporaneamente e prolungano proprio il sovraccarico da cui cercano di uscire.

Passare alla riserva invece di fallire

Nei percorsi sensibili alla latenza, definisci una catena di riserva. In un endpoint compatibile con OpenAI significa modificare una sola stringa — senza un secondo SDK e senza un secondo 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          # saturado — probar el siguiente nivel
    raise last

E solo allora esaminare il codice

Se i 529 compaiono solo per un tipo di richiesta mentre le altre chiamate funzionano contemporaneamente, non si tratta di un incidente generale: verifica se quel percorso invia prompt insolitamente grandi o si attiva in un ciclo chiuso. Se invece interessa improvvisamente tutte le chiamate e scompare da solo, si trattava di capacità — quindi il lavoro spetta al ritentativo e alla riserva, non a un refactoring.

Se chiami tramite Kunavo

Kunavo instrada Claude attraverso più percorsi di origine e il suo catalogo multimodello rende il passaggio tra provider una modifica del nome del modello usando la stessa chiave e lo stesso portafoglio — il modello precedente non richiede un secondo account. I 529 che comunque ti raggiungono non vengono mai addebitati. Capacità e prezzo sono domande diverse; per la seconda, le tariffe per modello sono disponibili in prezzi di Claude.

Domande frequenti

Un 529 è colpa mia?

No. È un problema di capacità lato provider. Le tue uniche responsabilità sono non amplificare l'incidente (backoff, jitter) e avere un'uscita di riserva se l'incidente dura più del tuo budget di latenza.

529 rispetto a 429: qual è la differenza?

429 significa che hai superato i tuoi limiti, mentre il server funziona correttamente. 529 significa che il server stesso è sovraccarico, mentre la tua quota è corretta. Entrambi possono essere ritentati; solo 429 include l'indicazione Retry-After.

Quanto dura normalmente un episodio 529?

Non è prevedibile né garantibile — per questo la risposta corretta è un backoff con limite massimo più una coda, non un'attesa codificata rigidamente. Se il tuo percorso ha un budget di latenza, la riserva subentra al posto dell'attesa.

Le chiamate che terminano con 529 vengono addebitate?

Tramite Kunavo no: una richiesta che termina con un errore non viene addebitata. Con un contratto diretto dipende dalle regole di fatturazione del provider interessato.

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.