Fehler-Antwortformat
Chat Completions, Responses, Messages und Gemini sind öffentliche Protokollgrenzen und keine Web-APIs. Native Protokollfehler werden nicht in das Web-Envelope{ success, data, error } verpackt. Das folgende Beispiel gilt für OpenAI-kompatible Gatewayfehler in Chat und Responses:
message und type vorhanden; code, param und Hinweiserweiterungen sind optional. Messages und Gemini verwenden ihre nativen Fehlerfamilien. Upstream-Validierungsfehler bleiben erhalten, wenn sie sicher zurückgegeben werden können; ein deterministisches 400/422 wechselt den Kanal nicht, und nach dem ersten ausgelieferten Byte wird nicht erneut versucht.
HTTP-Statuscodes
Fehlertypen
Authentifizierungsfehler (401)
Zahlungsfehler (402)
Zugriffsfehler (403)
Validierungsfehler (400)
model_not_found zurück.
Rate-Limit-Fehler (429)
Wenn Sie die Ratenbegrenzungen überschreiten:Retry-After-Header und das Feld retry_after geben beide die exakte Anzahl an Sekunden an, die vor einem erneuten Versuch gewartet werden soll.
Payload zu groß (413)
Wenn Eingabe oder Dateigröße die Grenzwerte überschreitet:- Bilddatei zu groß (max 20MB)
- Audiodatei zu groß (max 25MB)
- Eingabetext überschreitet die Kontextlänge des Modells
Upstream-Fehler (502, 503)
Wenn alle Kanäle fehlschlagen, enthält die Antwort alternative Modelle:
Fehlerbehandlung in Python
Fehlerbehandlung in JavaScript
Beste Vorgehensweisen
Exponentielles Backoff implementieren
Exponentielles Backoff implementieren
Wenn Sie rate-limited sind, warten Sie bei erneuten Versuchen schrittweise länger:
Timeouts setzen
Timeouts setzen
Setzen Sie immer vernünftige Timeouts, um hängende Anfragen zu vermeiden:
Fehler zum Debugging protokollieren
Fehler zum Debugging protokollieren
Protokollieren Sie die vollständige Fehlerantwort inklusive Request-ID für den Support:
Modellspezifische Fehler behandeln
Modellspezifische Fehler behandeln
Einige Modelle haben spezifische Anforderungen (z. B. maximale Tokens, Bildformate).
Validieren Sie Eingaben, bevor Sie Anfragen stellen.