De drie soorten 429
HTTP 429 is de standaardstatus 'te veel verzoeken'. Hier dekt het drie situaties, en het JSON-foutlichaam vertelt je welke.
| Error code | Wat het betekent | Typische oplossing |
|---|---|---|
rate_limited | Te veel verzoeken per minuut | Vertraag, verdeel verzoeken over de minuut |
concurrency | Te veel verzoeken die tegelijk lopen | Verminder parallelisme, wacht tot er weer slots vrijkomen |
Overbelasting, met Retry-After: 5 | Tijdelijke belasting van de service, niet jouw schuld | Wacht het aantal seconden uit de header en probeer opnieuw |
Lees eerst de code, want een oplossing voor één oorzaak helpt bij een andere niets. Je verzoeken per minuut halveren helpt niet als het echte probleem is dat 20 workers tegelijk afvuren.
Ken je limieten
De limieten hangen af van het type sleutel:
- Volledige sleutel: 8 gelijktijdige verzoeken en 300 verzoeken per minuut.
- Proefsleutel: 2 gelijktijdige verzoeken en 60 verzoeken per minuut.
Elk antwoord bevat X-RateLimit-Limit-Requests en X-RateLimit-Limit-Concurrency, zodat je client de bovengrens kunt uitlezen in plaats van deze hard te coderen. De proefsleutel is de gebruikelijke boosdoener voor nieuwe gebruikers: een script dat het goed doet met 1 verzoek tegelijk, begint te falen zodra je een thread pool van 4 toevoegt. De proef is bedoeld voor testen, en een volledige sleutel krijg je bij elke opwaardering vanaf $20 (zie de prijzenpagina voor bedragen en bonussen).
De bovenstaande cijfers gelden per sleutel. Als één sleutel wordt gedeeld door een webapp, een cronjob en het notebook van een collega, trekken ze allemaal uit hetzelfde totaal, en lijken de 429's willekeurig totdat je de drie werklasten optelt.
Waarom streaming gelijktijdigheidsfouten waarschijnlijker maakt
Een normaal verzoek houdt een gelijktijdigheids-slot een seconde of twee vast. Een gestreamd verzoek (stream: true) houdt het vast tot het laatste token is aangekomen en de stream sluit. Een lang antwoord kan een slot tientallen seconden bezet houden, dus 8 slots zijn snel op in een chatapp met meerdere actieve gebruikers.
Twee fouten veroorzaken het meeste probleem hier. De eerste is een stream verlaten zonder deze te sluiten: als de client stopt met lezen maar de verbinding open laat, blijft de slot bezet tot de verbinding eindigt. Sluit altijd het antwoord in een finally-blok, of gebruik de contextmanager van de SDK. De tweede is een stream opnieuw proberen door een tweede te openen terwijl de eerste nog actief is, wat de slotgebruiking precies verdubbelt op het moment dat je weinig slots hebt.
Als je app meer gelijktijdige lange streams nodig heeft dan je sleutel toestaat, zet dan nieuwe chats in de wachtrij aan je eigen kant en toon een korte wachttijd. Dat is beter dan gebruikers ruwe fouten te laten zien.
Python-code voor opnieuw proberen met backoff
Het patroon is eenvoudig: vang de 429, lees de code, wacht, probeer opnieuw met een groeiende vertraging en wat willekeurigheid, en geef op na een paar pogingen. Deze versie gebruikt het officiële openai-pakket tegen de basis-URL van de service:
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."}]))
Wanneer de header aanwezig is, gebruik deze dan als minimale wachttijd. Wanneer deze ontbreekt, werkt de exponentiële vertraging voor rate_limited omdat het venster per minuut voortschrijdt. De jitter voorkomt dat veel workers op hetzelfde moment opnieuw proberen.
Beperk gelijktijdige aanroepen zodat je zelden een 429 ziet
Retries behandelen het symptoom. Een semaphore voorkomt de meeste fouten door niet meer te verzenden dan je slotaantal. Stel deze iets onder de limiet zodat een retry of een dwaas verzoek nog ruimte heeft:
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())
Voor de limiet per minuut zijn 300 verzoeken per minuut gemiddeld 5 per seconde. Als je duizenden korte taken in batches verwerkt, voeg dan een korte slaap of een tokenemmer toe voor de semaphore. Omdat de SDK ook standaard zelf opnieuw probeert, stel max_retries expliciet in zodat je eigen logica en die van de SDK niet stapelen en de wachttijden vermenigvuldigen.
Reproduceer en inspecteer een 429 met curl
Voordat je code aanpast, kijk naar de ruwe respons. Voeg -i toe aan curl zodat de headers worden afgedrukt, en stuur een paar verzoeken parallel om de fout opzettelijk te provoceren:
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
Op een proefsleutel, die 2 verzoeken tegelijk toestaat, zouden de derde en vierde aanroepen status 429 moeten geven met een error code van concurrency. Bij een volledige sleutel zou je meer dan 8 tegelijk nodig hebben. Kijk naar drie dingen in elke reply: de statusregel, de Retry-After-header als die er is, en het error.code-veld in de JSON-body. Dit kleine experiment vertelt je meer dan een uur raden, en het geeft je een reproduceerbaar geval om te tonen aan support als er iets mis lijkt te zijn.
Ontwerp erop, niet eromheen
Behandel een 429 als een normaal evenement, zoals een time-out. Plaats modelaanroepen achter één functie, log elke retry met de reden, en exposeer een teller zodat je merkt wanneer de retries stijgen. Een stijgende retry-rate is een vroeg teken dat je verkeer de limieten van één sleutel te boven gaat, lang voordat gebruikers klagen. Voor chatproducten houdt een kleine in-memory wachtrij per gebruiker één druk account ervan af om alle 8 slots van de andere gebruikers in beslag te nemen.
Een korte foutopsporingslijst
- Log het volledige foutbericht en de
X-Request-Id-header voor elke 429. Het veld 'code' onderscheidtrate_limitedvanconcurrency. - Controleer of je sleutel een proefsleutel is. Zo ja, verwacht dan 2 gelijktijdige verzoeken en 60 per minuut.
- Tel elk programma dat de sleutel gebruikt, niet alleen degene die faalde.
- Zoek naar niet-gesloten streams, en naar loops die direct opnieuw proberen zonder vertraging. Een directe retry-loop verandert één 429 in honderd.
- Bevestig het saldo met
X-Balance-USDofGET /v1/balance. Een leeg saldo is een ander probleem dan een 429, maar controleren duurt enkele seconden.
Mislukte verzoeken worden niet in rekening gebracht, dus opnieuw proberen kost je geen tokens voor de afgewezen pogingen. Voor de volledige lijst van statuscodes en headers, zie de documentatie. Als je een sleutel nodig hebt met hogere limieten dan een proefsleutel, vraag een API-sleutel aan en laad op.
