KI-API-Fehler: 401, 403, 429 und 5xx
Diagnostizieren Sie Authentifizierung, Policies, Limits, Abbrüche und Upstream-Fehler schichtweise und entscheiden Sie sicher über Retries.
Ein HTTP-Status ist der Startpunkt einer KI-API-Diagnose, nicht die vollständige Ursache. Sichern Sie vor einem Retry Request-ID, UTC-Zeit, Endpunkt, Modell, Key-Namen, Gruppe, strukturierten Fehler und Zeitdaten. Ordnen Sie den Abbruch danach Client, Authentifizierung, Policy, Protokoll, Routing, Backend oder Downstream-Verbindung zu.
Erste Einordnung
| Status | Erste Bedeutung | Erste Aktion |
|---|---|---|
| 400 | Ungültiger Payload oder Vertrag | Korrigieren, nicht unverändert wiederholen |
| 401 | Fehlender, falscher oder abgelaufener Key | Authorization und aktuellen Key prüfen |
| 403 | Konto-, Modell-, Gruppen- oder IP-Policy | Key-Grenzen vor Kanälen prüfen |
| 404 | Falscher Pfad oder Modell-ID | Base URL und /v1/models prüfen |
| 429 | Quota-, Rate- oder Routenlimit | Grenze lokalisieren, begrenzt zurücksetzen |
| 499 | Downstream hat vor Abschluss abgebrochen | Deadlines, Abort, Proxy und First Output prüfen |
| 502/503/504 | Upstream-, Verfügbarkeits- oder Zeitproblem | Evidenz sichern, begrenzt ausweichen oder wiederholen |
Nach Schicht diagnostizieren
401 entsteht meist vor Routing. Prüfen Sie Authorization: Bearer ..., Key-Status, Host und alte Secrets im Deployment. Vollständige Keys gehören nie in Logs oder Tickets.
403 beweist keine Provider-Störung. Modelllimit, IP-Allowlist, Gruppenrecht oder Account-Policy können vor der Kanalauswahl greifen. Rufen Sie mit demselben Key /v1/models ab und lesen Sie den genauen Fehlercode.
Bei 429 muss klar sein, ob Key, Konto, Modellgruppe oder Route begrenzt. Beachten Sie Retry-After, verwenden Sie exponentielles Backoff mit Jitter und begrenzen Sie Versuche, Dauer und Parallelität. Mehr Keys umgehen ein Kontolimit nicht zwingend.
499 bedeutet, dass die Downstream-Verbindung endete. Beginnen Sie bei Abort-Signal, Browser, CDN, Load Balancer und Proxy; vergleichen Sie die erste effektive Ausgabe. Ein einzelner Datensatz belegt keinen Kanalausfall.
Retry-Entscheidung
- Ungültiger Request, Key oder Zugriff: Ursache korrigieren, nicht unverändert wiederholen.
- Rate Limit: nur erlaubt und begrenzt mit Backoff.
- Temporäre 502/503/504: nur idempotente Arbeit mit strengem Budget.
- Client-Abbruch: nur wenn das Ergebnis noch benötigt wird und Duplikate sicher sind.
- Tools oder Schreibeffekte: zuerst Anwendungs-Idempotenz schaffen.
Jeder Versuch kann neue Arbeit und Kosten erzeugen. Sicher teilbar sind ID, Zeit, Endpunkt, Streaming-Modus, Modell, Gruppe, Status, Fehlercode und Timing; nicht vollständiger Key, Prompt, Antwort, Body, E-Mail oder Klartext-IP. Danach helfen Routing und Streaming bei der Behebung.