Claude API 500 api_error e 502 Bad Gateway: una politica di ritentativo che recupera davvero

500 e 502 indicano un guasto, non un limite. Per questo sono l'unica classe di errori di questo gruppo che vale la pena ritentare quasi immediatamente, a differenza di 429, che è il tuo limite di frequenza, e 529, che indica che il provider è al completo. Ritentare quello sbagliato dei tre trasforma un piccolo incidente nel tuo incidente.

L’errore

due forme, stessa soluzione

// Straight from the model provider (HTTP 500)
{
  "type": "error",
  "error": { "type": "api_error", "message": "Internal server error" }
}

// From a gateway or proxy in between (HTTP 502)
{
  "error": {
    "message": "Failed to reach upstream provider",
    "type": "upstream_error",
    "code": "upstream_error",
    "param": null
  }
}

Cause e soluzioni in breve

Causa	Soluzione
Guasto transitorio lato provider	Ritenta con backoff esponenziale e jitter, con un massimo di ~5 tentativi.
Connessione accettata, poi nessuna risposta	Un blocco, non un errore. Limita separatamente il tempo al primo byte rispetto alla durata totale.
Un intermediario che restituisce il proprio 502	Non ha nulla a che vedere con il modello. Verifica se il corpo della risposta ha il formato del provider o quello di un proxy.
Ritentare alla cieca durante un incidente reale	Limita i tentativi e applica il backoff; altrimenti i tuoi ritentativi diventano parte dell'interruzione.

Separa 500 da 529 e 429 prima di scegliere una soluzione

429 è un limite di frequenza che stai superando: rallenta. 529 indica che il provider è al limite della capacità: applica un backoff molto più forte e più lungo. 500/502 è un guasto, di solito breve e spesso specifico di una singola richiesta. Solo il terzo caso merita un ritentativo rapido; trattarli tutti allo stesso modo è il motivo per cui i cicli di ritentativo peggiorano gli incidenti.

Ritenta i 5xx, mai i 4xx

Backoff esponenziale con jitter, massimo cinque tentativi. Lo stesso helper funziona per ogni provider: un 400 o un 422 fallirà allo stesso modo al tentativo successivo, quindi ritentarlo serve solo a spendere latenza per arrivare allo stesso errore.

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Limita separatamente il tempo al primo byte rispetto alla durata totale

Un unico timeout per l'intera richiesta non distingue una generazione lunga da una connessione interrotta. Imposta una scadenza breve per il primo byte e una più generosa per il resto; un blocco fallirà così rapidamente, mentre una risposta realmente lenta potrà continuare.

Registra stato e latenza per ogni tentativo

Senza registrazioni per tentativo, dopo l'accaduto un incidente del provider e il tuo timeout sembrano identici. Codice di stato, latenza e numero del tentativo bastano per distinguerli la mattina successiva.

Se chiami tramite Kunavo

A settembre 2026, ogni modello Claude su Kunavo viene servito tramite un unico canale upstream, quindi un 5xx proveniente da quel canale non viene ritentato all'interno della richiesta: ti arriva come 502 con il messaggio “Upstream provider error” (tipizzato come api_error su /v1/messages), e la richiesta viene registrata a costo zero. Il ritentativo nella richiesta di Kunavo viene eseguito solo per un modello con un secondo canale configurato: un timeout, un 5xx, un 429 o il rifiuto della chiave upstream di Kunavo viene ritentato su quel canale prima di arrivare a te, su /v1/messages, /v1/responses e sui modelli Claude in /v1/chat/completions. Uno stream viene trattenuto finché non arriva il primo contenuto, quindi anche un errore in uno stream non ancora iniziato viene ritentato; una volta che il contenuto fluisce, un errore a metà stream deve essere gestito da te. In ogni caso, mantieni lato tuo la politica di ritentativo indicata in questa pagina. Il routing alla base di questo comportamento è descritto nella nostra guida al gateway AI.

Domande frequenti

Mi viene addebitata una richiesta che restituisce 500?

Su Kunavo, no: le richieste non riuscite vengono registrate a costo zero. La fatturazione diretta con un provider varia, ma in genere un 5xx non viene addebitato.

Ritentare un 500 può produrre due completamenti?

Sì. Una richiesta può fallire dopo che il modello ha già generato la risposta. Se il lavoro produce effetti collaterali, rendilo idempotente a livello della tua applicazione prima di aggiungere ritentativi.

Qual è la differenza in una riga tra 500, 502 e 529?

500 indica un guasto del provider, 502 indica che qualcosa davanti a esso non riesce a raggiungerlo e 529 indica che il provider è al limite della capacità: ritenta presto i primi due e molto più tardi il terzo.

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.