Fehler

Der Fehler-Envelope

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

Das ist derselbe Envelope, den die eigene API von OpenAI verwendet, sodass Fehlerbehandlung, die gegen einen bestehenden OpenAI-kompatiblen Client geschrieben wurde, ohne Änderungen weiter funktionieren sollte: prüfen Sie zuerst den HTTP-Statuscode und lesen Sie error.message für eine Meldung, die es wert ist, an einen Entwickler weitergegeben oder geloggt zu werden. error.type ist eine stabile, maschinell auswertbare Kategorie, nützlich für Verzweigungslogik (erneut versuchen oder nicht, nach einem neuen API-Schlüssel fragen oder abwarten und es erneut versuchen), ohne den Freitext der Meldung parsen zu müssen.

Statuscodes und Typen

Status	Typ	Bedeutung
400	invalid_request_error	Die Anfrage selbst ist fehlerhaft aufgebaut: ein nicht erkanntes model, ein fehlendes oder leeres messages-Array, eine Nachricht mit einer nicht unterstützten Rolle oder eine fehlerhafte tools-Definition. Beheben Sie die Anfrage; ein erneuter Versuch ohne Änderung schlägt jedes Mal auf dieselbe Weise fehl.
401	authentication_error	Der Authorization-Header fehlt, ist fehlerhaft aufgebaut, oder der Schlüssel ist ungültig, abgelaufen oder widerrufen. Siehe Authentifizierung.
429	rate_limit_error	Zu viele Anfragen in kurzer Zeit mit diesem Schlüssel. Das Limit und wie man korrekt zurückschaltet finden Sie unter Rate Limits.
500	api_error	Ein unerwarteter serverseitiger Fehler, der nichts mit Ihrer Anfrage zu tun hat. Selten; sicher, es erneut zu versuchen, idealerweise mit einer kurzen Wartezeit davor.
503	api_error	Der Dienst kann die Anfrage vorübergehend nicht abschließen, typischerweise ein vorübergehendes Problem in der eigenen Generierungs-Infrastruktur von tAI, nicht etwas, das mit Ihrer Anfrage nicht stimmt. Sicher, es erneut zu versuchen.

Ein paar Beispiele

Ein unbekanntes Modell:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

Ein ungültiger oder abgelaufener Schlüssel:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

Ein vorübergehendes Problem beim Dienst:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

Fehler mitten im Stream

Sobald eine gestreamte Antwort begonnen hat (die Verbindung ist offen, und Chunks sind bereits eingetroffen), kann ein Fehler nicht mehr als normaler JSON-Fehler-Body mit einem Nicht-2xx-Status gemeldet werden, da der HTTP-Status und die Header zu Beginn des Streams bereits als 200 gesendet wurden. Stattdessen wird ein Fehler, der mitten im Stream auftritt, als sichtbarer Content-Chunk dargestellt (typischerweise ein kurzer Hinweis in eckigen Klammern), gefolgt von einem normalen Finish-Chunk und [DONE], statt dass die Verbindung einfach abbricht. Das genaue Format und warum der Stream so oder so garantiert sauber endet, finden Sie unter Streaming.

Was sich lohnt, erneut zu versuchen

Als Faustregel: 400- und 401-Fehler beschreiben etwas, das an der Anfrage oder am Schlüssel selbst nicht stimmt, und ein identischer erneuter Versuch schlägt jedes Mal identisch fehl, beheben Sie also zuerst das zugrunde liegende Problem. 429, 500 und 503 sind alle sicher, erneut zu versuchen, idealerweise mit einer kurzen Verzögerung und einer Obergrenze für die Gesamtzahl der Versuche, statt in einer engen Schleife zu wiederholen; wie man von einem 429 speziell korrekt zurückschaltet, finden Sie unter Rate Limits.