Errore 529 overloaded_error dell'API Claude — cosa significa e come gestirlo

Riprovare senza aggravare l'incidente

Tratta 529 come un 429 senza Retry-After: backoff esponenziale a partire da circa 2 secondi, con jitter, limitato a 30–60 secondi; dopo circa cinque tentativi rinuncia e inserisci il lavoro in coda. Il jitter è fondamentale: senza di esso, tutti i client tornano online contemporaneamente e prolungano esattamente il sovraccarico da cui stanno cercando di uscire.

Passare al fallback invece di interrompersi

Per i percorsi sensibili alla latenza, definisci una catena di fallback. Su un endpoint compatibile con OpenAI, è sufficiente modificare una sola stringa: nessun secondo SDK, nessun secondo account:

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          # überlastet — nächste Stufe versuchen
    raise last

Solo dopo controlla il tuo codice

Se 529 si verifica solo per un singolo tipo di richiesta mentre le altre chiamate nello stesso momento vanno a buon fine, non si tratta di un'interruzione del provider: verifica se quel percorso invia prompt insolitamente grandi o viene eseguito in un ciclo molto stretto. Se invece il problema colpisce tutte le chiamate contemporaneamente e poi scompare da solo, era un problema di capacità: il lavoro va gestito con retry e fallback, non con un refactoring.

Un 529 è colpa mia?

No. È un problema di capacità lato provider. La tua responsabilità consiste solo nel non aggravare l'incidente (backoff, jitter) e nell'avere una destinazione di fallback se l'incidente dura più a lungo del tuo budget di latenza.

529 o 429: qual è la differenza?

429 significa che hai superato i tuoi limiti e il server è sano. 529 significa che il server è sovraccarico e la tua quota è a posto. Entrambi gli errori sono ripetibili; solo 429 include un'indicazione Retry-After.

Quanto dura di solito una fase 529?

Non è prevedibile e non è possibile garantirlo: per questo la risposta corretta è un backoff con limite più una coda, non un tempo di attesa scritto nel codice. Se il tuo percorso ha un budget di latenza, il fallback deve intervenire al posto dell'attesa.

Le chiamate 529 non riuscite vengono addebitate?

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