Fehler, Ratenbegrenzungen & Zuverlässigkeit
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.
Wiederholungsversuche mit Backoff
Bei transienten Fehlern (429, 5xx) wiederhole mit exponentiellem Backoff + Jitter, begrenzt:
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.)
Ratenbegrenzungen
Limits gelten pro Account/Stufe (Anfragen und Tokens pro Minute). Wenn du eines erreichst, erhältst du 429 mit Timing-Hinweisen. Strategien: retry-after beachten, Spitzen glätten, Offline-Arbeit batchen und für umfangreiche Schritte ein günstigeres Modell verwenden (Ein Modell auswählen).
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 Einstellungen & Migration und die Modelltabelle.
- Führe deine Evals erneut aus, wenn du Modelle wechselst.