Home → Assistenza

Un 429 da un gateway API può significare due cose diverse

Cosa vedi

• 429 Too Many Requests
• {"code":"API_KEY_QUOTA_EXHAUSTED"}
• {"error":{"message":"Upstream rate limit exceeded, please retry later"}}
• A client with automatic retry that never stops retrying
• Insufficient account balance
• Concurrency limit exceeded for user, please retry later
• All available accounts are currently rate-limited. Please retry later.

Perché succede

HTTP non ha uno stato che significhi «hai finito i soldi». 402 Payment Required esiste ma non si usa quasi mai, quindi i gateway sovraccaricano il 429 sia per la fatturazione sia per la limitazione. I due casi sono opposti in tutto ciò che conta: uno è permanente finché non intervieni, l'altro è transitorio e si risolve da solo.

È importante perché la maggior parte dei meccanismi di retry degli SDK si basa solo sul codice di stato. Il client Python di OpenAI ritenta i 429 per impostazione predefinita. Puntalo su un gateway con saldo esaurito e consumerà tutti i tentativi su una richiesta che non può riuscire, per poi mostrare un timeout: e tu andrai a cercare un problema di rete che non esiste.

C'è una terza causa da conoscere, perché assomiglia alla seconda e si risolve in modo diverso: un limite di concorrenza per account. Il messaggio lo dice esplicitamente — Concurrency limit exceeded for user, please retry later. Non riguarda quante richieste hai inviato in un minuto, ma quante erano in corso nello stesso momento. Aspettare aiuta, ma la vera soluzione è limitare il parallelismo nel tuo client; è stato aumentarlo a causare l'errore.

Verifica se la causa è questa

Fai una richiesta e guarda il corpo invece dello stato:

curl -s -o /tmp/r.json -w '%{http_code}\n' \
  'YOUR_BASE_URL/chat/completions' \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"hi"}],"max_tokens":1}'

cat /tmp/r.json

Un codice o un messaggio che cita quota, balance o credit indica fatturazione. Tutto ciò che cita rate, busy o upstream indica limitazione. Se il corpo è vuoto, cerca l'header Retry-After: la sua presenza indica limitazione.

Come risolvere

1. Decidi in base al corpo prima di ritentareAnalizza il JSON e tratta i 429 di fatturazione come fatali. Ritentarli spreca i tuoi tentativi e nasconde la vera causa dietro un timeout.
2. Rispetta Retry-After quando c'èLe risposte di limitazione spesso lo includono. Se manca, un backoff esponenziale che parte da circa un secondo è un valore ragionevole; ritentare subito di solito peggiora la congestione.
3. Monitora il saldo separatamente dagli erroriUn saldo esaurito è un evento di business, non un incidente. La maggior parte dei gateway espone il saldo tramite la propria API o una dashboard: tieni d'occhio quel numero e non incontrerai mai questo 429 in produzione.
4. Limita le richieste simultanee, non solo la frequenzaSe il messaggio parla di concorrenza, un ciclo di retry più lento non aiuterà — il limite conta le richieste simultanee. Un semaforo attorno al tuo client, dimensionato su ciò che il gateway consente, risolve davvero il problema.
5. Non aumentare la concorrenza per risolvere un 429 di limitazionePiù richieste parallele contro un upstream congestionato producono più 429, non più throughput. Riduci la concorrenza e lascia lavorare il backoff.

Articoli correlati

Ultima verifica: 2026-10-01. Scritto a partire da problemi diagnosticati su un gateway compatibile con OpenAI in produzione, non raccolto da altri siti.