I tre tipi di 429
HTTP 429 è lo status standard "troppe richieste". Qui copre tre situazioni e il corpo JSON dell'errore ti dice in quale ti trovi.
| Codice di errore | Cosa significa | Soluzione tipica |
|---|---|---|
rate_limited | Troppe richieste al minuto | Rallenta, distribuisci le richieste nel minuto |
concurrency | Troppe richieste in esecuzione contemporaneamente | Riduci il parallelismo, attendi che gli slot si liberino |
Sovraccarico, con Retry-After: 5 | Carico temporaneo del servizio, non è colpa tua | Attendi il numero di secondi indicato nell'header, poi riprova |
Leggi prima il codice, perché una soluzione per una causa non vale per le altre. Ridurre a metà le richieste al minuto non aiuterà se il problema reale è che 20 worker sparano richieste simultaneamente.
Conosci i tuoi limiti
I limiti dipendono dal tipo di chiave:
- Chiave completa: 8 richieste concurrent e 300 richieste al minuto.
- Chiave trial: 2 richieste concurrent e 60 richieste al minuto.
Ogni risposta include X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency, così il tuo client può leggere il limite massimo senza doverlo impostare manualmente. La chiave di prova è spesso la causa per i nuovi utenti: uno script che funziona bene con 1 richiesta alla volta inizia a fallire quando aggiungi un thread pool da 4. La prova serve per i test e una chiave completa è disponibile con qualsiasi ricarica da $20 (vedi la pagina dei prezzi per importi e bonus).
I numeri sopra sono per chiave. Se una chiave è condivisa da un'app web, un cron job e il notebook di un collega, tutti attingono allo stesso pool e i 429 sembreranno casuali finché non sommerai i tre carichi di lavoro.
Perché lo streaming rende più probabili gli errori di concorrenza
Una richiesta normale mantiene uno slot di concorrenza per un secondo o due. Una richiesta in streaming (stream: true) lo mantiene fino all'arrivo dell'ultimo token e alla chiusura dello stream. Una risposta lunga può tenere occupato uno slot per decine di secondi, quindi 8 slot spariscono rapidamente in un'app chat con diversi utenti attivi.
Due errori causano la maggior parte dei problemi qui. Il primo è abbandonare uno stream senza chiuderlo: se il client smette di leggere ma lascia la connessione aperta, lo slot rimane occupato fino alla chiusura della connessione. Chiudi sempre la risposta in un blocco finally, o usa il context manager dell'SDK. Il secondo è ritentare uno stream aprendone un secondo mentre il primo è ancora vivo, il che raddoppia l'uso degli slot proprio quando ne sei a corto.
Se la tua app ha bisogno di più stream lunghi simultanei di quanto permetta la tua chiave, accoda le nuove chat lato client e mostra un breve stato di attesa. È meglio che far vedere errori grezzi agli utenti.
Codice di retry Python con backoff
Il pattern è semplice: intercetta il 429, leggi il codice, attendi, riprova con un ritardo crescente e un po' di casualità, e arrenditi dopo alcuni tentativi. Questa versione usa il pacchetto ufficiale openai contro l'URL base del servizio:
import random
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
max_retries=0, # we handle retries ourselves
)
def chat(messages, attempts=5):
for i in range(attempts):
try:
r = client.chat.completions.create(
model="uncensored",
messages=messages,
)
return r.choices[0].message.content
except RateLimitError as e:
headers = e.response.headers
wait = float(headers.get("Retry-After", 0))
if not wait:
wait = min(30, 2 ** i) # 1, 2, 4, 8, 16 seconds
wait += random.uniform(0, 1) # jitter
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(chat([{"role": "user", "content": "Reply with the word ok."}]))
Quando l'header è presente, usalo come attesa minima. Quando manca, il ritardo esponenziale funziona per rate_limited perché la finestra per minuto si sposta. Il jitter evita che molti worker ritentino nello stesso istante.
Imposta un tetto alle chiamate parallele così raramente vedrai un 429
I retry trattano il sintomo. Un semaforo previene la maggior parte dei casi impedendo di inviare più richieste del tuo conteggio di slot. Impostalo leggermente al di sotto del limite così un retry o una richiesta isolata abbiano ancora spazio:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6) # full key allows 8; use 1 on a trial key
async def ask(prompt):
async with sem:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main():
prompts = [f"Give one fact about the number {n}." for n in range(50)]
results = await asyncio.gather(*(ask(p) for p in prompts))
print(len(results))
asyncio.run(main())
Per il limite al minuto, 300 richieste al minuto sono in media 5 al secondo. Se batchezi migliaia di lavori brevi, aggiungi un piccolo sleep o un token bucket davanti al semaphore. Poiché l'SDK ritenta anche in modo autonomo per impostazione predefinita, imposta max_retries esplicitamente così la tua logica e quella dell'SDK non si impilano e moltiplicano i tempi di attesa.
Riproduci e ispeziona un 429 con curl
Prima di modificare il codice, guarda la risposta grezza. Aggiungi -i a curl così gli header vengono stampati, e lancia alcune richieste in parallelo per provocare l'errore intenzionalmente:
for i in 1 2 3 4; do
curl -i -s https://api.onekeyllmapi.com/v1/chat/completions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait
Su una chiave di prova, che permette 2 richieste alla volta, la terza e la quarta chiamata dovrebbero restituire status 429 e un codice di errore di concurrency. Con una chiave completa avresti bisogno di più di 8 simultanee. Guarda tre cose in ogni risposta: la riga di status, l'header Retry-After se presente, e il campo error.code nel corpo JSON. Questo piccolo esperimento ti dice più di un'ora di indovinare, e ti dà un caso riproducibile da mostrare al supporto se qualcosa sembra sbagliato.
Progetta per gestirlo, non per aggirarlo
Tratta un 429 come un evento normale, come un timeout. Metti le chiamate al modello dietro una funzione, registra ogni tentativo con il suo motivo ed esponi un contatore così noti quando i tentativi aumentano. Un tasso di tentativi crescente è un segnale precoce che il tuo traffico ha superato i limiti di una singola chiave, molto prima che gli utenti si lamentino. Per i prodotti chat, una piccola coda in memoria per utente impedisce a un account occupato di prendersi tutti gli 8 slot degli altri utenti.
Una breve checklist di debug
- Logga il corpo completo dell'errore e l'header
X-Request-Idper ogni 429. Il campo code separarate_limiteddaconcurrency. - Verifica se la tua chiave è una chiave di prova. Se sì, prevedi 2 richieste concorrenti e 60 al minuto.
- Conta ogni programma che usa la chiave, non solo quello che ha fallito.
- Cerca flussi non chiusi e cicli che ritentano istantaneamente senza ritardo. Un ciclo di ritentativi istantaneo trasforma un 429 in cento.
- Conferma il saldo con
X-Balance-USDoGET /v1/balance. Un saldo vuoto è un problema diverso da un 429, ma controllarlo richiede secondi.
Le richieste fallite non vengono addebitate, quindi ritentare non ti costa token per i tentativi rifiutati. Per l'elenco completo degli status code e degli header, vedi la documentazione. Se hai bisogno di una chiave con limiti superiori a una prova, richiedi una chiave API e ricarica il credito.
