Die drei Arten von 429
HTTP 429 ist der Standardstatus „too many requests“. Hier umfasst er drei Situationen, und der JSON-Fehlerkörper sagt dir, in welcher Situation du dich befindest.
| Fehlercode | Was es bedeutet | Typische Behebung |
|---|---|---|
rate_limited | Zu viele Anfragen pro Minute | Verlangsamen, Anfragen über die Minute verteilen |
concurrency | Zu viele Anfragen, die gleichzeitig ausgeführt werden | Parallelität verringern, auf freie Slots warten |
Überlastung mit Retry-After: 5 | Temporäre Last auf dem Dienst, nicht deine Schuld | Warte die Sekundenanzahl im Header ab und versuche es dann erneut |
Lies den Code zuerst, denn eine Behebung für eine Ursache hilft bei einer anderen nichts. Die Hälfte deiner Anfragen pro Minute zu reduzieren, hilft nicht, wenn das eigentliche Problem 20 Worker sind, die gleichzeitig feuern.
Kenne deine Limits
Die Limits hängen vom Schlüsseltyp ab:
- Voll-Key: 8 parallele Anfragen und 300 Anfragen pro Minute.
- Trial-Key: 2 parallele Anfragen und 60 Anfragen pro Minute.
Jede Antwort enthält X-RateLimit-Limit-Requests und X-RateLimit-Limit-Concurrency, damit dein Client die Obergrenze ausliest, statt sie hart zu codieren. Der Test-Schlüssel ist der übliche Übeltäter bei neuen Nutzern: Ein Skript, das bei 1 paralleler Anfrage noch funktioniert, schlägt fehl, wenn du einen Thread-Pool mit 4 hinzufügst. Der Test ist zum Ausprobieren gedacht, und ein voller Schlüssel kommt mit jeder Aufladung ab 20 $ (siehe Preisseite für Beträge und Boni).
Die obigen Zahlen gelten pro Schlüssel. Wenn ein Schlüssel von einer Web-App, einem Cron-Job und dem Notebook eines Kollegen geteilt wird, ziehen alle aus demselben Pool, und die 429s wirken zufällig, bis du die drei Arbeitslasten zusammenrechnest.
Warum Streaming Parallelitätsfehler wahrscheinlicher macht
Eine normale Anfrage belegt einen Parallelitäts-Slot für ein oder zwei Sekunden. Eine gestreamte Anfrage (stream: true) belegt ihn, bis das letzte Token ankommt und der Stream schließt. Eine lange Antwort kann einen Slot für Dutzende Sekunden belegen, sodass 8 Slots in einer Chat-App mit mehreren aktiven Nutzern schnell verschwinden.
Zwei Fehler verursachen den Großteil der Probleme hier. Der erste ist das Aufgeben eines Streams ohne ihn zu schließen: Wenn der Client aufhört zu lesen, die Verbindung aber offen lässt, bleibt der Slot belegt, bis die Verbindung endet. Schließe die Antwort immer in einem finally-Block oder verwende den Kontextmanager des SDKs. Der zweite ist das Wiederholen eines Streams, indem ein zweiter geöffnet wird, während der erste noch lebt, was die Slot-Nutzung genau dann verdoppelt, wenn du wenig Slots hast.
Wenn deine App mehr gleichzeitige lange Streams benötigt, als dein Schlüssel erlaubt, plane neue Chats auf deiner Seite in eine Warteschlange und zeige einen kurzen Wartezustand an. Das ist besser, als Nutzern rohe Fehleranzeigen zu zeigen.
Python-Retry-Code mit Backoff
Das Muster ist einfach: Fange die 429 ab, lese den Code, warte, versuche es erneut mit wachsender Verzögerung und etwas Zufälligkeit, und gib nach einigen Versuchen auf. Diese Version verwendet das offizielle openai-Paket gegen die Basis-URL des Dienstes:
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."}]))
Wenn der Header vorhanden ist, verwende ihn als Mindestwartzeit. Wenn er fehlt, funktioniert die exponentielle Verzögerung für rate_limited, weil sich das Minutenfenster verschiebt. Die Zufallsverzögerung verhindert, dass viele Worker gleichzeitig wiederholen.
Begrenze parallele Anfragen, um selten eine 429 zu sehen
Retries behandeln das Symptom. Ein Semaphore verhindert den Großteil davon, indem es nie mehr sendet als deine Slot-Anzahl. Stelle es etwas unter das Limit, damit eine Wiederholung oder eine fehlgeleitete Anfrage noch Platz hat:
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())
Für das Ratenlimit sind 300 Anfragen pro Minute durchschnittlich 5 pro Sekunde. Wenn du Tausende kurzer Jobs batchest, füge eine kurze Pause oder einen Token-Bucket vor das Semaphore. Da das SDK auch standardmäßig selbst wiederholt, setze max_retries explizit, damit deine eigene Logik und die des SDKs sich nicht stapeln und die Wartezeiten multiplizieren.
Reproduziere und untersuche eine 429 mit curl
Schau dir vor der Code-Änderung die rohe Antwort an. Füge -i zu curl hinzu, damit die Header ausgegeben werden, und feuere ein paar Anfragen parallel ab, um den Fehler absichtlich auszulösen:
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
Bei einem Trial-Key, der 2 Anfragen gleichzeitig erlaubt, sollten der dritte und vierte Aufruf mit Status 429 und einem Fehlercode von concurrency zurückkommen. Bei einem Voll-Key würdest du mehr als 8 gleichzeitig benötigen. Schau dir drei Dinge in jeder Antwort an: die Statuszeile, den Retry-After-Header, falls vorhanden, und das error.code-Feld im JSON-Body. Dieses kleine Experiment sagt dir mehr als eine Stunde Raten, und es gibt dir einen reproduzierbaren Fall, den du dem Support zeigen kannst, wenn etwas falsch aussieht.
Dafür designen, nicht darum herum
Behandle eine 429 als normales Ereignis, wie einen Timeout. Platziere Modellaufrufe hinter einer Funktion, protokolliere jede Wiederholung mit ihrem Grund und stelle einen Zähler bereit, damit du bemerkst, wenn die Wiederholungen steigen. Eine steigende Wiederholungsrate ist ein frühes Zeichen dafür, dass dein Traffic die Limits eines einzelnen Schlüssels überschritten hat, lange bevor Nutzer sich beschweren. Für Chat-Produkte hält eine kleine In-Memory-Warteschlange pro Benutzer einen ausgelasteten Account davon ab, allen anderen alle 8 Slots zu nehmen.
Eine kurze Debugging-Checkliste
- Protokolliere den vollständigen Fehlerkörper und den
X-Request-Id-Header für jede 429. Das Code-Feld unterscheidetrate_limitedvonconcurrency. - Prüfe, ob dein Key ein Trial-Key ist. Wenn ja, erwarte 2 parallele Anfragen und 60 pro Minute.
- Zähle jedes Programm, das den Schlüssel verwendet, nicht nur das, das fehlgeschlagen ist.
- Suche nach nicht geschlossenen Streams und nach Schleifen, die sofort ohne Verzögerung wiederholen. Eine sofortige Wiederholungsschleife verwandelt eine 429 in hundert.
- Bestätige den Saldo mit
X-Balance-USDoderGET /v1/balance. Ein leerer Saldo ist ein anderes Problem als eine 429, aber das Prüfen dauert Sekunden.
Fehlgeschlagene Anfragen werden nicht berechnet, daher kostet dich das Wiederholen keine Token für die abgelehnten Versuche. Für die vollständige Liste der Statuscodes und Header sieh dir die Dokumentation an. Wenn du einen Schlüssel mit höheren Limits als einem Test-Schlüssel benötigst, hole dir einen API-Schlüssel und lade auf.
