Fehlercodes und Fehlerbehebung

Fehlerursache eingrenzen

1. Notieren Sie tatsächlichen HTTP-Status, Anfragemethode und Pfad. HTTP-Status und Anwendungsfehlercode beschreiben unterschiedliche Ebenen; ersetzen Sie keinen durch den anderen.
2. Lesen Sie Fehlerfelder entsprechend dem aufgerufenen Protokoll. Native, OpenAI-, Claude- und Gemini-Antworten haben nicht alle dieselbe Struktur.
3. Prüfen Sie bei Streaming auch Fehlerereignisse und Abschlusszustand, bei asynchronen Aufträgen den status. HTTP 200 garantiert keine erfolgreiche Generierung.
4. Verwenden Sie die folgende Tabelle, um die Anfrage zu korrigieren oder eine Wiederholung zu beurteilen. message ist erklärender Text, kein stabiler Enum-Wert; verzweigen Sie nicht anhand seiner Formulierung.

Aufzählung der Plattformfehlercodes

Dies ist die vollständige Aufzählung der Anwendungsfehlercodes der Plattform. Namen sind Referenzbezeichnungen; code-Werte in Antworten sind Zahlen. „Häufiger HTTP-Status“ dient der Fehlerbehebung und ist keine feste Zuordnung für jeden Endpunkt. Verwenden Sie den tatsächlichen HTTP-Status und Antwortkörper. Ein vom Anbieter durchgereichter code gehört möglicherweise nicht zu dieser Aufzählung.

HTTP 429 allein unterscheidet Raten- und Parallelitätslimits nicht zuverlässig. Unterscheiden Sie diese nur anhand eines ausdrücklich vorhandenen numerischen Fehlercodes. Prüfen Sie Modellkennungen in der Modellliste; schreiben Sie model-Werte nicht eigenständig um.

Fehler nach Protokoll lesen

Die folgenden Beispiele zeigen häufige von der Plattform erzeugte Strukturen, kein für jeden Fehler garantiertes Einheitsformat. Authentifizierungsfehler können aus unterschiedlichen Verarbeitungsschichten stammen; durchgereichte Anbieterantworten können eigene Strukturen, Zeichenfolgencodes oder Typen behalten. Erkennen Sie vor dem Parsen die tatsächliche Struktur. Ist sie unbekannt, erhalten Sie Originalfelder und HTTP-Status, statt eine Umwandlung zu erzwingen.

Native Plattform-APIs

Lesen Sie gewöhnlich error.code und error.message. requestId kann fehlen.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Manche Fehler verwenden oberste Felder code und message. Clients sollten dies tolerieren und das Fehlen eines error-Objekts nicht als Erfolgsbeleg werten. Parametervalidierungsantworten können ebenfalls ohne numerischen Fehlercode sein. Behandeln Sie einen fehlenden Code als unbekannt, statt einen zu erfinden.

OpenAI-kompatible APIs

Häufige Plattformfehler verwenden die obersten Felder code, message und type; sie sind nicht unbedingt in error eingeschlossen.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type ist eine Protokollkategorie; code ist in dieser Struktur der numerische Plattformfehlercode. api_error allein entscheidet nicht über die Eignung einer Wiederholung. Durchgereichte Anbieter- und Streamingfehler können ein verschachteltes error enthalten; verarbeiten Sie die tatsächliche Protokollantwort. Siehe Chat Completions und Responses.

Claude-kompatible APIs

In der üblichen Struktur ist der oberste type gleich error, die genaue Kategorie steht in error.type, die Beschreibung in error.message. Diese Struktur enthält keinen numerischen Plattform-code. Erfinden Sie keinen.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

Die Plattform erzeugt lokal die folgenden Claude-Fehlertypen. Dies ist keine vollständige Aufzählung der Anbieterfehlertypen.

Siehe Claude-Nachrichten.

Fehler im Gemini-Stil

Bei einer Antwort im Gemini-Stil lesen Sie error.code, error.message und error.status. status ist hier eine Zeichenfolgenkategorie, kein HTTP-Status oder Zustand eines asynchronen Auftrags.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Von der Plattform erzeugte Fehler dieser Struktur verwenden numerische Plattformwerte für code. Die lokale Zuordnung des Zeichenfolgenfelds status steht unten; sie zählt nicht alle Anbieterstatuswerte auf.

503 hat Vorrang und verwendet UNAVAILABLE, nicht INTERNAL. Anbieterantworten können andere Bedeutungen für code und status verwenden. Wenden Sie die Plattformfehlercodetabelle nicht auf jeden numerischen Gemini-Code an.

Sicher wiederholen

Beachten Sie einen gültigen Retry-After-Header, falls vorhanden. Gehen Sie nicht davon aus, dass jeder Fehler ihn enthält. Eine automatische Wiederholung einer nicht idempotenten Generierungsanfrage kann sie erneut ausführen und weitere Kosten verursachen. Diese Seite verspricht keine allgemeine Unterstützung von Idempotenzschlüsseln; selbst hinzugefügtes Idempotency-Key garantiert keine Deduplizierung.

Haben Sie bereits eine jobId, fragen Sie diesen Auftrag ab, bevor Sie einen weiteren erstellen. Ohne jobId und bei ungewissem Ergebnis bewahren Sie Anfragekennung und Zeitstempel für die Untersuchung auf.

Streams und asynchrone Aufträge

SSE-Anfragen

Nach Beginn von SSE kann der HTTP-Status 200 bleiben, während ein späterer Fehler als Ereignis oder Nutzlast im Stream gemeldet wird. Parsen Sie Ereignisse und Daten des gewählten Protokolls und prüfen Sie den normalen Abschluss. Bei Fehler oder unerwartetem Abbruch gelten Teiltexte oder Teilbilder nicht als vollständig erfolgreiches Ergebnis. Ereignisnamen und Nutzlasten unterscheiden sich je Endpunkt. Prüfen Sie nicht nur ein festes error-Feld und werten Sie nicht „irgendein Text empfangen“ als Erfolg.

Asynchrone Aufträge

Eine Erstellungsantwort mit data.jobId bedeutet Annahme, nicht abgeschlossene Generierung. Eine erfolgreiche HTTP-Antwort beim Abfragen eines Auftrags bedeutet eine erfolgreiche Abfrage. Sie müssen weiterhin data.status des Auftrags prüfen:

• PENDING, CONNECT, PROCESSING: gemäß Jobs-Dokumentation weiter abfragen.
• COMPLETED: outputResult lesen.
• FAILED, CANCELLED: Abfragen beenden und Auftrags-ID sowie bereinigte Antwortdaten für die Untersuchung aufbewahren.

Fehlerdetails können in data.outputResult.error stehen. Das Feld ist optional und nicht für jeden fehlgeschlagenen Auftrag garantiert. Verwenden Sie Jobs nur, wenn die Erstellungsantwort ausdrücklich eine jobId liefert. Wenden Sie Auftragspolling nicht auf Endpunkte an, die Ergebnisse direkt per JSON oder SSE zurückgeben.

Diagnose für Nutzer und KI-Assistenten

Geben Sie dem Support oder einem KI-Assistenten die folgenden bereinigten Informationen. Verwenden Sie unknown für fehlende Felder und unknown für den HTTP-Status, wenn keine HTTP-Antwort eintraf. Erhalten Sie Feldpfade und Originaltypen, etwa error.code: 10000 (number) oder error.code: "invalid_api_key" (string). Wandeln Sie einen Zeichenfolgen-code nicht automatisch in einen numerischen Plattformcode um und erfinden Sie fehlende Felder nicht aus message, HTTP-Status oder Modellnamen.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Lesen Sie requestId aus dem Antwortkörper oder dem Antwortheader X-Request-ID, falls vorhanden. Behalten Sie jobId als Zeichenfolge, um bei langen Zahlen keine Genauigkeit zu verlieren. Übermitteln Sie nur minimale bereinigte Anfrageparameter. Entfernen Sie API-Schlüssel, Tokens, Cookies, vollständige Authentifizierungsheader, persönliche Daten, private Prompts und Eingabedateiinhalte. Entfernen Sie URL-Abfrageparameter sowie Ein- oder Ausgabe-URLs mit Signaturen oder Zugangsdaten. Fügen Sie keine vollständigen Anfrageprotokolle ohne Prüfung ein.

KI-Assistenten sollten beobachtete Felder von möglichen Ursachen unterscheiden und fehlende Informationen benennen. Unzureichende Belege dürfen nicht als Nachweis für Erfolg, Nichtausführung oder Kostenfreiheit einer Anfrage gelten.