KI-API-Fehler: 401, 403, 429 & 5xx diagnostizieren

Diagnostizieren Sie Authentifizierung, Zugriffsrichtlinien, Ratenlimits, Client-Abbrüche und Fehler des Dienstanbieters – und wann eine Wiederholung sicher ist.

KI-API-Fehler: 401, 403, 429 & 5xx diagnostizieren

KI-API-Fehler lassen sich am leichtesten diagnostizieren, wenn der Statuscode als Beginn einer Untersuchung behandelt wird und nicht als vollständige Ursache. Sichern Sie vor einer Wiederholung Anfrage-ID, Zeitstempel, Endpunkt, Modell, Namen des API-Schlüssels, ausgewählte Gruppe, Antwortinhalt und Zeitdaten.

Ziel ist es, die Ebene zu ermitteln, die die Anfrage abgelehnt oder beendet hat: Client, Authentifizierung, Zugriffsrichtlinie, Protokollvalidierung, Routing, Modell-Backend oder Downstream-Verbindung.

Was gängige Statuscodes meist bedeuten

Status Erste Einordnung Erste Maßnahme
400 Ungültige Anfragestruktur, ungültiges Feld oder verletzter Protokollvertrag Anfrageinhalt mit dem gewählten Endpunkt abgleichen; nicht unverändert wiederholen
401 Fehlende, fehlerhaft formatierte, deaktivierte, abgelaufene oder ungültige Zugangsdaten Authorization-Header und aktuellen Schlüssel prüfen
403 Authentifiziert, aber durch Konto, Modell, Gruppe, IP oder Richtlinie blockiert Schlüsseleinschränkungen und Modell- bzw. Gruppenzugriff prüfen, bevor Kanäle getestet werden
404 Falscher Endpunktpfad oder nicht verfügbare Modell-ID Basis-URL, Pfad und authentifizierte Modellliste prüfen
429 Limit für Anfragerate, Kontingent oder geeignete Routen erreicht Kontingent und Gruppenlimits prüfen; begrenztes Backoff oder konfigurierten Fallback nutzen
499 Der Downstream-Client hat die Verbindung vor dem Abschluss getrennt oder abgebrochen Client-Fristen, Abbrüche, Proxys und Zeit bis zur ersten Ausgabe prüfen
500 Fehler in der internen Verarbeitung oder im Adapter Anfrage-ID sichern; nur wiederholen, wenn der Vorgang sicher ist
502/503 Fehlerhafte Antwort des Dienstanbieters, nicht verfügbare Route oder vorübergehender Kapazitätsengpass Routing-Nachweise prüfen und begrenzten Fallback oder Wiederholungen nutzen
504 Ein Zeitbudget des Gateways oder des Dienstanbieters ist abgelaufen Zeit bis zur ersten Ausgabe und Gesamtzeit mit den Client-Fristen vergleichen

Diese Einordnungen sind Ausgangspunkte für die Diagnose. Den tatsächlichen Grund für einen bestimmten Aufruf bestimmen der Fehlerinhalt und der Anfragedatensatz.

401 diagnostizieren, bevor Sie das Modell ändern

Ein 401 tritt normalerweise auf, bevor ein sinnvolles Modell-Routing stattfindet. Prüfen Sie, ob:

  • der Header Authorization: Bearer ... verwendet wird;
  • die Anwendung keine Anführungszeichen, Leerzeichen oder Platzhalterwerte mitsendet;
  • der Schlüssel aktiviert und nicht abgelaufen ist;
  • die Anfrage an den vorgesehenen Modelflare-Host gesendet wird;
  • ein Secret-Manager oder ein Deployment noch einen älteren, bereits rotierten Schlüssel enthält.

Fügen Sie den vollständigen Schlüssel nicht in Protokolle oder Support-Nachrichten ein. Reproduzieren Sie das Problem mit einem eigenen Testschlüssel, falls der Schlüssel offengelegt sein könnte, und widerrufen Sie anschließend die kompromittierten Zugangsdaten.

403 zuerst als Fehler der Zugriffsrichtlinie diagnostizieren

Ein 403 bedeutet nicht automatisch, dass ein Dienstanbieter die Anfrage abgelehnt hat. Die Authentifizierung kann erfolgreich sein, während der Zugriff noch vor der Kanalauswahl scheitert, weil:

  • der Schlüssel das angeforderte Modell einschränkt;
  • die IP-Zulassungsliste des Schlüssels die beobachtete Client-IP nicht enthält;
  • das Konto die ausgewählte Modellgruppe nicht nutzen darf;
  • der Benutzer oder der Schlüssel durch eine Richtlinie deaktiviert ist;
  • die angeforderte Funktion für diese Route nicht zulässig ist.

Rufen Sie /v1/models mit demselben Schlüssel ab, prüfen Sie dessen Gruppen- und Modellgrenzen und vergleichen Sie den genauen Fehlercode. Wurde kein Kanal ausgewählt, kann ein Wechsel der Kanäle beim Dienstanbieter die vorgelagerte Richtlinienentscheidung nicht beheben.

429 diagnostizieren, ohne eine Wiederholungswelle auszulösen

Ein 429 ist ein Kapazitäts- oder Richtliniensignal und keine Aufforderung, sofort in einer engen Schleife erneut anzufragen. Ermitteln Sie, ob das Limit zum Kontingent des Schlüssels, zum Konto, zur Modellgruppe oder zur ausgewählten Route gehört.

Bei wiederholbaren Ratenlimits:

  1. beachten Sie Retry-After, falls vorhanden;
  2. verwenden Sie exponentielles Backoff mit Jitter;
  3. begrenzen Sie die Anzahl der Versuche und die Gesamtdauer;
  4. halten Sie die Parallelität der Anwendung innerhalb einer bekannten Grenze;
  5. verwenden Sie geordnete Fallback-Gruppen nur, wenn sie das angeforderte Modell und Protokoll beibehalten.

Zusätzliche API-Schlüssel umgehen ein Anfragelimit auf Konto- oder Gruppenebene nicht unbedingt.

499 vom Aufrufer ausgehend diagnostizieren

Modelflare kann 499 erfassen, wenn die Downstream-Verbindung des Clients endet, bevor die Antwort abgeschlossen ist. Beginnen Sie beim Aufrufer:

  • Wurde ein Abbruchsignal ausgelöst?
  • Hat Client, Load Balancer, CDN oder Reverse Proxy ein Leerlauf- oder Gesamt-Timeout erreicht?
  • Hat der Benutzer die Seite geschlossen oder den Agenten gestoppt?
  • Hat der Stream ein Tool-Event ohne sichtbaren Text geliefert?
  • Wie viel Zeit verging bis zur ersten effektiven Ausgabe?

Ein einzelner 499-Eintrag belegt keinen Kanalausfall. Vergleichen Sie andere Anfragen im selben Zeitraum mit demselben Modell und derselben Gruppe, bevor Sie die Routing-Richtlinie ändern.

5xx-Fehler nach Ebene unterscheiden

Bewahren Sie bei 5xx den ursprünglichen Status und die Fehlerdetails auf, statt im Client jeden Fehler in einen generischen 500 umzuwandeln.

  • Ein Validierungs- oder Adapterfehler mit 500 kann deterministisch sein und unverändert erneut fehlschlagen.
  • Ein 502 kann auf eine ungültige oder unvollständige Antwort des Dienstanbieters hinweisen.
  • Ein 503 kann bedeuten, dass keine geeignete Route verfügbar ist oder eine vorübergehende Nichtverfügbarkeit besteht.
  • Ein 504 zeigt, dass ein Zeitbudget abgelaufen ist; die verantwortliche Ebene muss aber noch ermittelt werden.

Nutzen Sie die Zeitdaten der Anfrage, die ausgewählte Gruppe, die für den Support verfügbaren Kanalnachweise und zeitnahe Anfragen, um eine einzelne fehlerhafte Antwort von einem anhaltenden Problem einer Route zu unterscheiden.

Entscheiden, ob wiederholt wird

Fehlerklasse Standardentscheidung zur Wiederholung
Ungültiger Anfrageinhalt oder nicht unterstütztes Protokoll Anfrage korrigieren; nicht unverändert wiederholen
Ungültiger Schlüssel oder verweigerter Zugriff Zugangsdaten oder Richtlinie korrigieren; nicht unverändert wiederholen
Kontingent aufgebraucht Kontingent bewusst erhöhen oder neu verteilen; keine Schleife
Ratenlimit Mit begrenztem Backoff wiederholen, sofern zulässig
Vorübergehender 502/503/504 Idempotente Arbeit mit strengem Versuchsbudget wiederholen
Abbruch durch den Client Nur wiederholen, wenn der Benutzer das Ergebnis noch braucht und Duplikate unbedenklich sind
Nebenwirkungen durch Tools oder Schreibvorgänge Vor einer Wiederholung Idempotenz auf Anwendungsebene sicherstellen

Wiederholungen erzeugen neue Arbeit und können neue Kosten verursachen. Protokollieren Sie jeden Versuch und verdecken Sie den ursprünglichen Fehler nicht hinter einem späteren Erfolg.

Nachweise sicher erfassen

Erfassen Sie für den Support oder die Analyse einer Störung:

  • Anfrage-ID und UTC-Zeitstempel;
  • Endpunkt und Streaming-Modus;
  • angefordertes Modell und ausgewählte Gruppe;
  • HTTP-Status und strukturierten Fehlercode;
  • Gesamtzeit und Zeit bis zur ersten effektiven Ausgabe;
  • ob der Aufrufer abgebrochen hat;
  • eine bereinigte Beschreibung der verwendeten Funktion, etwa Tools oder Bildeingabe.

Geben Sie den vollständigen API-Schlüssel, Prompt, Antwortinhalt, rohen Anfrageinhalt, E-Mail-Adressen oder Klartext-IP-Adressen nur weiter, wenn ein genehmigter sicherer Prozess dies ausdrücklich erfordert.

Nachdem Sie die fehlerhafte Ebene gefunden haben, nutzen Sie Zuverlässiges KI-API-Routing für das Fallback-Design und den Streaming-Leitfaden für Event- und Timeout-Fehler.

Häufige Fragen

Beweist ein 403, dass ein Anbieter ausgefallen ist?

Nein. Ein 403 kann durch Konto-, Schlüssel-, Modell-, Gruppen-, IP- oder Funktionsrichtlinien entstehen, bevor eine Route zum Dienstanbieter ausgewählt wird. Prüfen Sie zuerst den Anfragedatensatz und den Fehlercode.

Ist 499 ein üblicher Modellfehler des Dienstanbieters?

Nein. In den Anfragedatensätzen von Modelflare steht er für einen Downstream-Abbruch, der vor dem Abschluss beobachtet wurde. Untersuchen Sie die Fristen von Aufrufer und Proxy, bevor Sie ihn als Modellfehler behandeln.

Sollte jede 5xx-Antwort wiederholt werden?

Nein. Wiederholen Sie nur Vorgänge, die sicher wiederholt werden können, verwenden Sie ein begrenztes Budget für Versuche und Zeit und bewahren Sie den ersten Fehler auf. Deterministische Adapter- oder Anfrageprobleme lösen sich durch Wiederholung nicht.