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.
Schichtspezifische Prüfungen
Bei 401
Prüfen Sie Authorization: Bearer ..., zusätzliche Anführungszeichen oder Leerzeichen, den Key-Status und veraltete Secrets im Deployment. Der Fehler tritt meist vor dem Modellrouting auf.
Bei 403
Prüfen Sie mit demselben Key erlaubte Modelle, IP-Liste, Gruppenzugriff und Kontorichtlinie. Wurde noch kein Kanal gewählt, behebt ein Providerwechsel die frühere Ablehnung nicht.
Bei 429
Ermitteln Sie, ob Key, Konto, Gruppe oder Route begrenzt. Beachten Sie Retry-After, verwenden Sie exponentielle Wartezeiten mit Zufallsanteil und begrenzen Sie Versuche, Gesamtdauer und Parallelität.
Bei 499
Beginnen Sie beim Client: Abbruchsignal, geschlossener Tab, CDN, Load Balancer und Proxy-Zeitlimits. Vergleichen Sie den Abbruchzeitpunkt mit der ersten effektiven Ausgabe; ein einzelner 499 belegt keinen Kanalausfall.
5xx-Fehler unterscheiden
500 kann ein deterministischer Adapterfehler sein, 502 eine ungültige oder unvollständige Upstream-Antwort, 503 eine vorübergehend fehlende Route und 504 ein ausgeschöpftes Zeitbudget. Bewahren Sie den Originalstatus und wiederholen Sie nur sichere Vorgänge mit striktem Limit.
Sichere Diagnosebelege
- Anfrage-ID und UTC-Zeit;
- Endpunkt und Streaming-Modus;
- angefordertes Modell und gewählte Gruppe;
- HTTP-Status und strukturierter Fehlercode;
- Gesamtdauer und Zeit bis zur ersten effektiven Ausgabe;
- Hinweis auf einen Clientabbruch;
- bereinigte Funktionsbeschreibung wie Tools oder Bilder.
Vollständige Keys, Prompts, Antworten, Request Bodies, E-Mail-Adressen oder Klartext-IP-Adressen gehören nur in einen ausdrücklich genehmigten sicheren Prozess.
Häufige Fragen
Beweist 403 einen Providerausfall?
Nein. Konto, Key, Modell, Gruppe, IP oder Funktionsrichtlinie können die Anfrage vor der Providerauswahl ablehnen.
Ist 499 ein üblicher Upstream-Modellfehler?
Nein. In Modelflare-Datensätzen bezeichnet er einen Downstream-Abbruch vor Abschluss der Antwort.
Sollte jeder 5xx wiederholt werden?
Nein. Wiederholen Sie nur sicher wiederholbare Arbeit, begrenzen Sie Anzahl und Gesamtdauer und bewahren Sie den ersten Fehler.