Claude API 529 overloaded_error — significato e gestione corretta

Progetta retry che non peggiorino l’incidente

Tratta il 529 come un "429 senza Retry-After". Usa un backoff esponenziale che inizi da circa 2 secondi, con jitter, un limite di 30–60 secondi e circa 5 tentativi prima di rinunciare e trasferire la richiesta in coda. È il jitter a fare la differenza: senza di esso tutti i client tornerebbero nello stesso momento, prolungando proprio il sovraccarico da cui si cerca di uscire.

Non far fallire la richiesta: deviala

Per i percorsi sensibili alla latenza, prepara una catena di fallback. Se l’endpoint è compatibile con OpenAI, devi cambiare una sola stringa: non servono altri SDK né altri 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

Metti in dubbio il tuo codice per ultimo

Se solo determinati tipi di richieste ricevono 529 mentre le altre chiamate nello stesso momento riescono, non si tratta di un’interruzione generale. Controlla se quel percorso invia prompt insolitamente grandi o se trasmette richieste a raffica in un ciclo breve. Al contrario, se tutte le chiamate ricevono 529 contemporaneamente e il problema si risolve spontaneamente dopo un po’, la causa è la capacità. In quel caso devi intervenire su retry e fallback, non sul refactoring.

Il 529 dipende da me?

No. È un problema di capacità del provider. La nostra responsabilità consiste in due sole cose: non amplificare l’incidente (backoff e jitter) e predisporre una destinazione alternativa quando l’incidente supera il tempo di latenza accettabile.

Qual è la differenza tra 529 e 429?

Il 429 indica che hai superato il tuo limite, mentre il server è normale. Il 529 indica che il server è sovraccarico, mentre i tuoi limiti e il tuo saldo sono normali. Entrambi possono essere ritentati, ma solo il 429 include l’indicazione Retry-After.

Quanto dura di solito un 529?

Non è prevedibile né garantito. Per questo la soluzione corretta è "backoff con limite + coda", non un tempo di attesa fisso scritto nel codice. Se quel percorso ha un limite di latenza, il fallback deve subentrare invece di aspettare.

Le chiamate fallite con 529 vengono comunque addebitate?

Tramite Kunavo, no. Le richieste che terminano con un errore non vengono fatturate. In caso di contratto diretto, si applicano le regole di fatturazione del singolo provider.