Errore 529 overloaded_error dell'API Claude — cos'è e come gestirlo

Riprovare senza aggravare l'incidente

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

Passare al fallback invece di interrompersi

Per i percorsi sensibili alla latenza, definisci una catena di fallback. Su un endpoint compatibile con OpenAI, devi cambiare 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          # saturé — passer au palier suivant
    raise last

E solo dopo controlla il tuo codice

Se i 529 compaiono solo per un singolo tipo di richiesta mentre le altre chiamate nello stesso momento vanno a buon fine, non si tratta di un'interruzione generalizzata: 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 una riscrittura.

Un 529 è colpa mia?

No. È un problema di capacità lato provider. Le tue uniche responsabilità sono non aggravare l'incidente (backoff, jitter) e avere una via di uscita 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 funziona correttamente. 529 significa che il server stesso è sovraccarico e la tua quota è a posto. Entrambi possono essere ripetuti; solo 429 fornisce un'indicazione Retry-After.

Quanto dura un periodo 529?

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

Le chiamate 529 vengono fatturate?

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