Fehler, Rate Limits & Zuverlässigkeit
- Die HTTP-Fehlerübersicht lesen und wissen, welche Statuscodes wiederholt vs. behoben werden müssen
- Transiente Fehler mit exponentiellem Backoff und Jitter, gedeckelt, wiederholen
- Rate Limits mit retry-after, Glättung, Batching und günstigeren Modellen behandeln
- Den eigenen Code gegen Modell-Deprecations und Migrationen absichern
Produktionscode spricht mit einem Netzwerkdienst und muss daher mit Fehlern rechnen. Ein wenig Struktur an dieser Stelle macht den Unterschied zwischen einer instabilen und einer verlässlichen Integration aus.
Die Fehlerübersicht
Typische HTTP-Status, die du behandeln wirst:
| Status | Bedeutung | Was zu tun ist |
|---|---|---|
| 400 | Ungültige Anfrage | Korrigiere den Payload; nicht unverändert wiederholen |
| 401 | Falscher/fehlender API-Schlüssel | Anmeldedaten überprüfen |
| 403 | Nicht erlaubt | Zugriff/Berechtigungen überprüfen |
| 429 | Ratenbegrenzt | Zurückfahren und wiederholen (retry-after beachten) |
| 500/529 | Serverfehler / überlastet | Mit Backoff wiederholen |
- Die SDKs stellen diese als typisierte Ausnahmen bereit, sodass du sauber verzweigen kannst, statt Strings zu parsen.
Wiederholungen mit Backoff
Bei transienten Fehlern (429, 5xx) wiederhole mit exponentiellem Backoff + Jitter, gedeckelt:
import time, random
for attempt in range(5):
try:
return client.messages.create(...)
except (RateLimitError, APIStatusError) as e:
if attempt == 4 or not should_retry(e):
raise
time.sleep(min(2 ** attempt + random.random(), 30))
- Viele SDKs wiederholen transiente Fehler automatisch — kenne die Voreinstellung deines Clients, bevor du eigene hinzufügst, sonst verdoppelst du womöglich die Wiederholungen.
Rate Limits
Limits gelten pro Account/Stufe (Anfragen und Tokens pro Minute). Wenn du eines erreichst, erhältst du 429 mit Timing-Hinweisen. Strategien, um unter der Obergrenze zu bleiben:
Guided walkthrough1 of 4
- Wenn du ein 429 erhältst, lies den Timing-Hinweis in der Antwort und warte so lange, bevor du erneut versuchst.
- Verteile Anfragen über die Zeit, statt sie alle auf einmal abzufeuern.
- Verlagere umfangreiche, nicht-interaktive Jobs in die Stapelverarbeitung.
- Leite umfangreiche Schritte an ein günstigeres Modell weiter — siehe Ein Modell auswählen.
Siehe Ein Modell auswählen zur Wahl des richtigen Modells für umfangreiche Schritte.
Modellmigration
Modell-IDs sind datiert/versioniert und werden eingestellt. Schütze dich davor:
- Lies die Modell-ID aus einer Konfiguration, nicht aus verstreuten Literalen.
- Beobachte Einstellungen — siehe Beobachtung von Deprecations & Migration und die Modelltabelle.
- Führe deine Evals erneut aus, wenn du Modelle wechselst.
- 400/401/403 sind dein Fehler — korrigiere die Anfrage oder die Anmeldedaten, wiederhole nicht blind. 429 und 500/529 sind wiederholbar.
- Wiederhole transiente Fehler mit exponentiellem Backoff + Jitter, gedeckelt (z. B. min(2 ** attempt + random(), 30)).
- Bei 429: retry-after beachten, Spitzen glätten, Offline-Arbeit batchen und umfangreiche Schritte an ein günstigeres Modell weiterleiten.
- Lies Modell-IDs aus einer Konfiguration, beobachte Deprecations und führe Evals beim Modellwechsel erneut aus.