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

Il 529 è l'unico errore Claude che il tuo codice non ha causato: Anthropic è sovraccarica. Non si può correggere, ma lo si può assorbire correttamente. Servono retry pazienti, un modello di riserva e mai tentativi immediati che amplifichino l'incidente.

L’errore

risposta (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

Cause e soluzioni in breve

Causa	Soluzione
Saturazione del provider (giorni di lancio, incidenti regionali)	Backoff esponenziale con jitter. Consulta la pagina di stato del provider invece di ripetere il deploy.
Il picco di traffico è caduto durante un incidente parziale	Distribuisci i job in batch; dieci minuti di attesa sono spesso sufficienti.
Retry immediato in un ciclo	Riprovare subito moltiplica il carico e prolunga l'incidente per tutti, incluso te.

Esegui il retry in modo responsabile

Tratta il 529 come un 429 senza intestazione retry-after: backoff esponenziale a partire da circa 2 s, con jitter, tetto di 30–60 s, rinuncia dopo circa 5 tentativi e accoda il lavoro. Lo stesso ramo di codice che gestisce il 429 va bene anche per il 529.

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

Cambia modello invece di abbandonare la richiesta

Nei percorsi sensibili alla latenza, definisci un modello di riserva: all'interno della stessa famiglia (Sonnet → Haiku) il comportamento resta simile; tra provider (Claude → GPT) puoi superare un intero incidente. In un endpoint compatibile con OpenAI basta cambiare una stringa.

failover.py

PREFERIDOS = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

Non confondere 529 con 429 o 402

429 significa che hai superato i tuoi limiti (il server funziona). 529 significa che il server è sovraccarico (la tua quota è disponibile). 402 significa saldo insufficiente. I tre errori si assomigliano nei log ma richiedono correzioni completamente diverse: solo 429 e 529 devono essere ripetuti.

Se chiami tramite Kunavo

Su Kunavo lo stesso catalogo multimodello è accessibile tramite un'unica chiave e un unico saldo, quindi il failover tra provider dell'esempio precedente consiste nel cambiare il nome del modello: non servono un secondo account o una seconda registrazione. Le richieste che falliscono non vengono addebitate. Capacità e prezzo sono domande separate; per la seconda, le tariffe per token sono disponibili in nostra guida ai prezzi dell'API Claude.

Domande frequenti

L'errore 529 è colpa mia?

No. È un problema di capacità del provider. Le tue uniche responsabilità sono non amplificare il problema (backoff con jitter) e avere una destinazione alternativa se l'incidente dura più del tuo budget di latenza.

Qual è la differenza tra 529 e 429?

429 significa che hai superato i tuoi limiti; 529 significa che il server è sovraccarico. Entrambi possono essere ripetuti, ma solo il 429 di solito include un'indicazione retry-after.

Mi verrà addebitata una richiesta che ha restituito 529?

Non dovrebbe: la richiesta non ha prodotto token. Su Kunavo, le richieste fallite non vengono detratte dal saldo.

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.