Errore Claude API 529 overloaded_error — cosa significa e come superarlo

Impedire che i retry amplifichino il guasto

Gestisci 529 come un «429 senza Retry-After»: backoff esponenziale a partire da circa 2 secondi, con jitter, limite di 30–60 secondi, poi rinuncia dopo circa cinque tentativi e inserisci il lavoro in coda. La parte davvero efficace è il jitter: senza di esso, tutti i client tornano nello stesso istante e prolungano identica la congestione da cui cercano di fuggire.

Non crollare: aggira il problema

Definisci in anticipo una catena di fallback per i percorsi sensibili alla latenza. Su un endpoint compatibile con OpenAI basta cambiare una stringa — non serve collegare un altro SDK né aprire un altro 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          # 過載 —— 試下一個
    raise last

Solo alla fine torna a sospettare del tuo programma

Se solo un tipo di richiesta restituisce 529 mentre le altre chiamate nello stesso momento funzionano, non si tratta di un guasto generale: controlla se quel percorso invia prompt insolitamente grandi o invia richieste consecutive in un ciclo molto breve. Al contrario, se tutte le chiamate iniziano contemporaneamente a restituire 529 e poi si risolvono da sole, la causa è la capacità — devi intervenire su retry e fallback, non fare refactoring.

529 è un problema mio?

No. È un problema di capacità lato provider. La tua responsabilità consiste solo in due cose: non amplificare il guasto (backoff e jitter) e avere un percorso alternativo quando il guasto supera il tuo budget di latenza.

Qual è la differenza tra 529 e 429?

429 significa che hai superato il tuo limite, mentre il server è sano; 529 significa che il server è sovraccarico e la tua quota è a posto. Entrambi possono essere ritentati, ma solo 429 include un'indicazione Retry-After.

Quanto dura di solito un 529?

Non è prevedibile né garantibile — perciò la risposta corretta è «backoff limitato con coda», non un tempo di attesa fisso nel codice. Se quel percorso ha un budget di latenza, deve subentrare un fallback, non l'attesa.

Le chiamate che falliscono con 529 vengono addebitate?

Tramite Kunavo no: le richieste che terminano con un errore non vengono conteggiate nella fatturazione. Se hai un contratto diretto con il provider, dipende dalle sue regole di fatturazione.