Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Fehlercodes

API-Fehlercodes verstehen und Fehler beheben.

Dieser Leitfaden gibt dir einen Überblick über Fehlercodes, die bei der Arbeit mit der API und unserer offiziellen Python-Bibliothek auftreten können. Zu jedem aufgeführten Fehlercode findest du in einem eigenen Abschnitt weitere Hinweise.

API-Fehler

Code Überblick
400 - Ungültiger Wert für service_tier Ursache: Die angeforderte oder von der API ermittelte Servicestufe ist für das Projekt nicht zulässig.
Lösung: Setze service_tier auf eine für das Projekt zulässige Stufe oder ändere die zulässigen Servicestufen in den Projekteinstellungen.
401 - Ungültige Authentifizierung Ursache: Die Authentifizierungsdaten sind ungültig.
Lösung: Prüfe, ob du für die Anfrage den richtigen API-Schlüssel und die richtige Organisation verwendest.
401 - Falscher API-Schlüssel angegeben Ursache: Der API-Schlüssel in deiner Anfrage ist falsch.
Lösung: Prüfe, ob du den richtigen API-Schlüssel verwendest, leere den Browsercache oder erstelle einen neuen Schlüssel.
401 - Für die API-Nutzung musst du Mitglied einer Organisation sein Ursache: Dein Konto gehört keiner Organisation an.
Lösung: Kontaktiere uns, damit wir dich einer neuen Organisation hinzufügen, oder bitte die für deine Organisation zuständige Person, dich in eine Organisation einzuladen.
401 - IP-Adresse nicht zugelassen Ursache: Die IP-Adresse, von der deine Anfrage stammt, steht nicht auf der Liste der zugelassenen IP-Adressen für dein Projekt oder deine Organisation.
Lösung: Sende die Anfrage von der richtigen IP-Adresse aus oder aktualisiere die Einstellungen für zugelassene IP-Adressen.
403 - Land, Region oder Gebiet nicht unterstützt Ursache: Du greifst von einem Standort auf die API zu, an dem der Zugriff nicht unterstützt wird.
Lösung: Weitere Informationen findest du in der Liste der unterstützten Länder und Gebiete.
429 - Credits aufgebraucht Code: credit_balance_exhausted
Ursache: Deine Organisation hat alle im Voraus bezahlten Credits aufgebraucht.
Lösung: Lade Credits auf, um die API weiter zu nutzen.
429 - Ratenlimit für Anfragen erreicht Ursache: Du sendest Anfragen in zu kurzer Folge.
Lösung: Verteile deine Anfragen über die Zeit und halte dich an die Wartezeit im Header Retry-After, sofern er vorhanden ist. Lies den Leitfaden zu Ratenlimits.
429 - Anfragerate senken Typ: rate_limit_error
Code: slow_down
Ursache: Deine Anfragerate ist zu schnell gestiegen.
Lösung: Halte dich an die Wartezeit im Header Retry-After, sofern er vorhanden ist. Senke die Anfragerate und erhöhe sie anschließend schrittweise.
429 - Ausgabenlimit der Organisation erreicht Code: organization_spend_limit_exceeded
Ursache: Deine Organisation hat ihr verbindliches Ausgabenlimit erreicht.
Lösung: Erhöhe das Ausgabenlimit deiner Organisation oder hebe es auf.
429 - Ausgabenlimit des Projekts erreicht Code: project_spend_limit_exceeded
Ursache: Dein Projekt hat sein verbindliches Ausgabenlimit erreicht.
Lösung: Erhöhe das Ausgabenlimit in den Projekteinstellungen oder hebe es dort auf.
429 - Nutzungslimit der Organisation erreicht Code: organization_usage_limit_exceeded
Ursache: Deine Organisation hat das von OpenAI zugewiesene Nutzungslimit erreicht.
Lösung: Beantrage die Genehmigung eines höheren Nutzungslimits oder kontaktiere den Support.
500 - Serverfehler beim Verarbeiten deiner Anfrage Ursache: Auf unseren Servern ist ein Fehler aufgetreten.
Lösung: Warte kurz und sende die Anfrage erneut. Kontaktiere uns, wenn das Problem weiterhin besteht. Prüfe die Statusseite.
503 - Modell vorübergehend überlastet Typ: service_unavailable_error
Code: server_is_overloaded
Ursache: Das angeforderte Modell ist vorübergehend überlastet.
Lösung: Halte dich an die Wartezeit im Header Retry-After, sofern er vorhanden ist, und sende die Anfrage anschließend erneut.

Prüfe bei Abrechnungsfehlern error.code, um die genaue Ursache zu ermitteln. Der allgemeinere Fehlertyp error.type kann weiterhin insufficient_quota lauten.

Bei Fehlern im Zusammenhang mit der Abrechnung, dem Ausgabenlimit oder dem Nutzungskontingent erhältst du durch erneute Anfragen keinen API-Zugriff. Lade zuerst Credits auf oder passe das betreffende Limit an, bevor du eine weitere Anfrage sendest.

Fehler im WebSocket-Modus

Wenn du den WebSocket-Modus der Responses API verwendest, können zusätzlich folgende Fehler auftreten:

  • previous_response_not_found: Die zu previous_response_id gehörende Antwort lässt sich anhand der verfügbaren Zustandsdaten nicht ermitteln. Sende die Anfrage mit dem vollständigen Eingabekontext erneut und setze dabei previous_response_id auf null.
  • websocket_connection_limit_reached: Die Verbindung hat ihre Höchstdauer von 60 Minuten erreicht. Öffne eine neue WebSocket-Verbindung und fahre fort.

Fehlertypen der Python-Bibliothek

Die Python-Bibliothek löst RateLimitError bei Antworten mit dem Statuscode 429 und InternalServerError bei Antworten mit dem Statuscode 503 aus. Wenn deine Fehlerbehandlung bei Drosselung und Überlastung bisher nur eine dieser Klassen abgefangen hat, fange beide ab und prüfe error.code. Bei überlasteter Videoverarbeitung erhältst du beispielsweise jetzt 503 statt 429. Die Änderungen für die einzelnen Endpunkte findest du in den Migrationshinweisen.

Typ Überblick
APIConnectionError Ursache: Die Verbindung zu unseren Diensten ist fehlgeschlagen.
Lösung: Prüfe deine Netzwerkeinstellungen, Proxy-Konfiguration, SSL-Zertifikate oder Firewallregeln.
APITimeoutError Ursache: Die Anfrage hat das Zeitlimit überschritten.
Lösung: Warte kurz und sende die Anfrage erneut. Kontaktiere uns, wenn das Problem weiterhin besteht.
AuthenticationError Ursache: Dein API-Schlüssel oder dein Token war ungültig, abgelaufen oder widerrufen.
Lösung: Prüfe, ob dein API-Schlüssel oder Token korrekt und aktiv ist. Möglicherweise musst du im Dashboard deines Kontos einen neuen Schlüssel oder ein neues Token erstellen.
BadRequestError Ursache: Deine Anfrage war fehlerhaft aufgebaut oder es fehlten erforderliche Parameter, etwa ein Token oder eine Eingabe.
Lösung: Der Fehlermeldung solltest du entnehmen können, wo der Fehler liegt. Prüfe anhand der Dokumentation für die aufgerufene API-Methode, ob du gültige und vollständige Parameter sendest. Möglicherweise musst du auch Codierung, Format oder Größe der Anfragedaten prüfen.
ConflictError Ursache: Eine andere Anfrage hat die Ressource aktualisiert.
Lösung: Versuche erneut, die Ressource zu aktualisieren. Stelle dabei sicher, dass keine andere Anfrage gleichzeitig versucht, sie zu aktualisieren.
InternalServerError Ursache: Auf unserer Seite ist ein Fehler aufgetreten.
Lösung: Warte kurz und sende die Anfrage erneut. Kontaktiere uns, wenn das Problem weiterhin besteht.
NotFoundError Ursache: Die angeforderte Ressource existiert nicht.
Lösung: Prüfe, ob du die richtige Ressourcenkennung verwendest.
PermissionDeniedError Ursache: Du hast keinen Zugriff auf die angeforderte Ressource.
Lösung: Prüfe, ob du den richtigen API-Schlüssel, die richtige Organisations-ID und die richtige Ressourcen-ID verwendest.
RateLimitError Ursache: Du hast dein zugewiesenes Ratenlimit erreicht oder das Anfragevolumen zu schnell erhöht.
Lösung: Verteile deine Anfragen über die Zeit. Beachte Retry-After, sofern der Header vorhanden ist, und halte die von dir festgelegten Grenzen für Wiederholungsversuche ein. Mehr dazu erfährst du im Leitfaden zu Ratenlimits.
UnprocessableEntityError Ursache: Die Anfrage ließ sich trotz korrekten Formats nicht verarbeiten.
Lösung: Sende die Anfrage erneut.

Anhaltende Fehler

Wenn das Problem weiterhin besteht, kontaktiere unser Supportteam per Chat und gib Folgendes an:

  • Das verwendete Modell
  • Die erhaltene Fehlermeldung und den Fehlercode
  • Die gesendeten Anfragedaten und Header
  • Den Zeitstempel und die Zeitzone der Anfrage
  • Weitere Angaben, die uns bei der Fehlersuche helfen können

Unser Supportteam untersucht das Problem und meldet sich so schnell wie möglich bei dir. Bei vielen Supportanfragen kann es zu längeren Wartezeiten kommen. Du kannst auch einen Beitrag in unserem Community-Forum veröffentlichen. Lass dabei sensible Informationen weg.

Fehler behandeln

Wir empfehlen dir, Fehler, die die API zurückgibt, in deinem Code zu behandeln. Dafür kannst du dich am folgenden Codebeispiel orientieren:

import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra",
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("Failed to connect to the OpenAI API:", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("OpenAI API request exceeded its rate limit:", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API returned an error:", error.status, error.message);
  } else {
    throw error;
  }
}