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

Fehler und Wiederherstellung

Erfahre, was Fehler der Agents API bedeuten und wie du danach sicher fortfährst.

Informationen zu allgemeinen HTTP-Fehlern und SDK-Ausnahmen findest du im Leitfaden zu Fehlercodes.

Fehler untersuchen

Prüfe bei Anfragefehlern die HTTP-Antwort. Tritt der Fehler während eines Turns oder beim Einrichten der Umgebung auf, prüfe die Ereignisse und den gespeicherten Zustand.

Fehler bei Was du prüfen solltest
API-Anfrage Prüfe den HTTP-Status und das error-Objekt in der Antwort.
Turn Wenn du agent.session.turn.failed empfängst, rufe den Turn ab und prüfe status und error.
Sitzung Wenn du agent.session.failed empfängst, rufe die Sitzung ab und prüfe status und error.
Umgebung Lies environment.error im Ereignis agent.session.environment.failed. Siehe Fehlerbehebung für die Sandbox.

Verwende bei strukturierten Fehlern error.code in der Anwendungslogik und error.message, um den Fehler zu erklären. Bei der Validierung einer Anfrage kann error.param angeben, welches Feld du korrigieren musst. Stelle sicher, dass deine Fehlerbehandlung auch bei unbekannten Codes und fehlendem param funktioniert.

In der Beta-API (OpenAI-Beta: agents=v1) enthält das Feld error einer Sitzung entweder eine Meldung als Zeichenkette oder null. Den Fehlercode der Sitzung findest du im zugehörigen SSE-Ereignis error.

Fehler bei API-Anfragen

Diese Fehler betreffen die Anfrage an die Agents API. Davon zu unterscheiden sind Turn-Fehler, die erst nach Beginn der Verarbeitung zurückgegeben werden.

Code Überblick
400: invalid_request_error Ursache: Ein Eingabe- oder Konfigurationswert ist ungültig oder zu groß.
Lösung: Korrigiere das Feld, das in error.param oder error.message angegeben ist. Siehe Ungültige Eingaben korrigieren.
400: invalid_beta Ursache: Der Header OpenAI-Beta enthält einen ungültigen Wert.
Lösung: Prüfe, welchen Header die von dir verwendete API-Version erfordert.
400: agent_not_persisted Ursache: Die angegebene agent_id gehört zu einem Agenten, der nur innerhalb einer Sitzung verfügbar ist.
Lösung: Erstelle einen gespeicherten Agenten und verwende seine ID.
400: invalid_otlp_endpoint, invalid_otlp_header Ursache: Der Tracing-Endpunkt oder die Header sind ungültig.
Lösung: Korrigiere deine Tracing-Konfiguration.
401: unauthorized; 403: forbidden Ursache: Die Authentifizierung ist fehlgeschlagen oder die nötige Zugriffsberechtigung fehlt.
Lösung: Beachte die allgemeinen Hinweise zu Authentifizierung und Berechtigungen.
404: not_found_error, model_not_found Ursache: Die Ressource oder das Modell ist für diese Anfrage nicht verfügbar.
Lösung: Prüfe die ID, das Modell und das Projekt. Prüfe auch, ob die Ressource gelöscht wurde.
409: conflict_error Ursache: Der Vorgang ist mit dem aktuellen Zustand der Ressource nicht vereinbar.
Lösung: Lies die Meldung und rufe den aktuellen Zustand ab, bevor du es erneut versuchst.
409: executor_version_incompatible Ursache: Die Version des Executors wird nicht unterstützt.
Lösung: Aktualisiere den Executor und versuche es erneut.
424: mcp_server_startup_failed Ursache: Ein MCP-Server konnte nicht starten.
Lösung: Prüfe die Konfiguration und die Zugangsdaten des Servers. Siehe Verbindungsprobleme beheben.
429: files_api_rate_limit_exceeded Ursache: Dateianfragen haben das Ratenlimit der Files API für dein Benutzerkonto überschritten.
Lösung: Sende weniger Anfragen gleichzeitig und beachte die Hinweise zu den Ratenlimits der Files API.
500: internal_error Ursache: Im Dienst ist ein unerwarteter Fehler aufgetreten.
Lösung: Prüfe vor einem erneuten Versuch, welche Arbeit bereits gespeichert wurde. Beachte die allgemeinen Hinweise zu Serverfehlern.
503: service_unavailable_error, server_is_overloaded Ursache: Der Dienst oder eine seiner Abhängigkeiten ist vorübergehend nicht verfügbar oder überlastet.
Lösung: Beachte die allgemeinen Hinweise zu HTTP 503 und prüfe vor einem erneuten Versuch, welche Arbeit bereits gespeichert wurde.

Ratenlimits der Files API

Anfragen zum Erstellen einer Sitzung oder zum Anhängen von Dateien können HTTP 429 mit files_api_rate_limit_exceeded zurückgeben. Die Agents API prüft Dateien über die Files API. Diese Prüfungen werden auf das Kontingent des authentifizierten Benutzerkontos für die Files API angerechnet. Für jede angehängte Datei kann eine eigene Prüfung erforderlich sein.

{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

Sende weniger Anfragen gleichzeitig, die auf Dateien zugreifen. Verlängere die Wartezeit zwischen den Versuchen exponentiell und begrenze die Anzahl der Versuche. Wenn du Anfragen sofort wiederholst, kann das Kontingent weiterhin ausgeschöpft bleiben.

Diese HTTP-Antwort bedeutet, dass der angeforderte Vorgang fehlgeschlagen ist. Eine Sitzung oder ein Turn kann dagegen auch nach einer erfolgreichen Antwort auf die Erstellungsanfrage noch asynchron fehlschlagen. Prüfe error.code, um den Ratenlimitfehler zu erkennen, statt den Meldungstext zu vergleichen.

Turn-Fehler

Bei einem fehlgeschlagenen Turn findest du status: "failed" und ein error-Objekt mit den Feldern code und message. Ist das Modell überlastet, kann der Fehler beispielsweise so aussehen:

{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

Turn-Fehlercodes haben keinen eigenen HTTP-Status. Bei Überlastung verwendet ein fehlgeschlagener Turn beispielsweise server_overloaded. Eine HTTP-Antwort kann server_is_overloaded enthalten.

Code Überblick
invalid_request Ursache: Die Eingabe oder die Konfiguration ist ungültig.
Lösung: Korrigiere die in der Meldung beschriebene Eingabe, bevor du es erneut versuchst.
context_length_exceeded Ursache: Die Eingabe ist zu groß für das Kontextfenster des Modells.
Lösung: Kürze die Eingabe. Ist die Unterhaltung zu lang, starte eine neue Sitzung mit einer kürzeren Zusammenfassung.
session_budget_exceeded Ursache: Das Nutzungsbudget der Sitzung ist ausgeschöpft.
Lösung: Starte eine neue Sitzung, um fortzufahren.
credit_balance_exhausted Ursache: Die Organisation hat keine API-Credits mehr.
Lösung: Beachte die Hinweise zum Credit-Guthaben.
project_spend_limit_exceeded Ursache: Das Projekt hat seine verbindliche Ausgabenobergrenze erreicht.
Lösung: Beachte die Hinweise zur Ausgabenobergrenze für Projekte.
organization_spend_limit_exceeded Ursache: Die Organisation hat ihre verbindliche Ausgabenobergrenze erreicht.
Lösung: Beachte die Hinweise zur Ausgabenobergrenze für Organisationen.
organization_usage_limit_exceeded Ursache: Die Organisation hat das von OpenAI festgelegte Nutzungslimit erreicht.
Lösung: Beachte die Hinweise zum Nutzungslimit für Organisationen.
usage_limit_exceeded Ursache: Ein Abrechnungs- oder Nutzungslimit wurde erreicht. Ein genauerer Fehlercode liegt nicht vor.
Lösung: Folge den allgemeinen Hinweisen zu Abrechnungsfehlern.
rate_limit_exceeded Ursache: Die Anfragen haben ein geltendes Ratenlimit überschritten.
Lösung: Folge der Anleitung für erneute Versuche.
server_overloaded Ursache: Der Modelldienst ist vorübergehend überlastet.
Lösung: Warte etwas, bevor du die ausstehende Arbeit erneut anstößt. Hält die Überlastung an, wechsle für spätere Turns das Modell.
flex_unavailable Ursache: Die Flex-Verarbeitung ist vorübergehend nicht verfügbar.
Lösung: Versuche es später erneut oder stelle die Servicestufe der Sitzung für spätere Turns um. Wähle dafür die Standardverarbeitung (default).
connection_failed, request_timeout, server_error, internal_error Ursache: Ein Verbindungsfehler, eine Zeitüberschreitung oder ein Dienstfehler hat den Abschluss des Turns verhindert.
Lösung: Prüfe, welche Arbeit bereits gespeichert wurde. Versuche es dann erneut und begrenze die Anzahl der Versuche.
authentication_error Ursache: Der Zugriff auf das Modell ist wegen der Zugangsdaten oder Berechtigungen fehlgeschlagen.
Lösung: Beachte die allgemeinen Hinweise zu Authentifizierung und Berechtigungen.
resource_not_found Ursache: Das angeforderte Modell oder die angeforderte Ressource ist nicht verfügbar.
Lösung: Prüfe das Modell und die Sitzungskonfiguration, bevor du es erneut versuchst.
sandbox_error Ursache: Die Umgebung konnte einen Vorgang nicht abschließen.
Lösung: Prüfe den Umgebungsfehler und behebe das Konfigurations- oder Verbindungsproblem.
executor_version_incompatible Ursache: Der Executor kann diesen Turn nicht ausführen.
Lösung: Aktualisiere den Executor. Wenn die Sitzung nicht fehlgeschlagen ist, versuche es in derselben Sitzung erneut.
active_turn_not_steerable Ursache: Der aktive Turn kann keine weiteren Eingaben annehmen.
Lösung: Warte, bis der Turn beendet ist, bevor du eine weitere Nachricht sendest.
cyber_policy, misalignment_policy_violation Ursache: Sicherheitssysteme haben die Anfrage blockiert.
Lösung: Prüfe, ob die Anfrage den geltenden Sicherheitsanforderungen entspricht, bevor du eine überarbeitete Eingabe sendest.

Sitzungs- und Umgebungsfehler

Ein fehlgeschlagener Turn bedeutet nicht zwangsläufig, dass auch die Sitzung fehlgeschlagen ist. Rufe die Sitzung ab, um festzustellen, ob du sie fortsetzen kannst. Hat status den Wert requires_action, führe die erforderlichen Aktionen aus. Ist die Sitzung fehlgeschlagen, behebe die Ursache und erstelle eine neue Sitzung mit den Eingaben, die du weiterhin benötigst.

Code Überblick
environment_connection_failed, environment_connection_timeout Ursache: Die Sandbox konnte keine Verbindung herstellen oder der Verbindungsaufbau hat zu lange gedauert.
Lösung: Prüfe, ob der Executor startet und Netzwerkzugriff hat. Prüfe bei selbst gehosteten Umgebungen auch die Verbindungskonfiguration.
sandbox_error Ursache: Beim Einrichten der Sandbox oder bei der Ausführung in der Sandbox ist ein Fehler aufgetreten.
Lösung: Prüfe die Setup-Befehle, Pakete und Eingabedateien sowie den Umgebungsfehler.
executor_version_incompatible Ursache: Die Executor-Version der Sitzung wird nicht unterstützt.
Lösung: Aktualisiere den Executor, bevor du eine neue Sitzung erstellst.
idle_timeout Ursache: Die gehostete Umgebung ist wegen Inaktivität abgelaufen.
Lösung: Erstelle eine neue Sitzung und übergib die Eingaben erneut.
internal_error Ursache: Aufgrund eines internen Fehlers wurde die Sitzung oder die Umgebung nicht betriebsbereit.
Lösung: Warte etwas und wiederhole das Setup. Wende dich an den Support, wenn es weiterhin fehlschlägt.

Wiederherstellung

Anfragen bei vorübergehenden Fehlern wiederholen

Gehe bei Ratenlimits, Überlastung, Zeitüberschreitungen und vorübergehenden Dienstausfällen wie folgt vor. Liegt der Fehler an ungültigen Eingaben, Zugangsdaten oder Abrechnungslimits, behebe zuerst die Ursache.

  1. Prüfe das Ergebnis. Falls eine Sitzung erstellt wurde, rufe die Sitzung, den Turn und die gespeicherten Elemente ab. Ist der Turn noch aktiv, verfolge ihn weiter. Ist er abgeschlossen, verwende sein Ergebnis.
  2. Prüfe die bereits ausgeführten Aktionen. Auch ein fehlgeschlagener Turn kann bereits Dateien geändert oder externe Tools aufgerufen haben. Prüfe, welche Auswirkungen diese Aktionen hatten, bevor du den Agenten aufforderst, die Arbeit zu wiederholen.
  3. Warte und begrenze die Anzahl der Versuche. Folge den allgemeinen Hinweisen zu erneuten Versuchen. Halte die in Retry-After angegebene Wartezeit aus der HTTP-Antwort ein und lege eine Höchstzahl an Versuchen oder eine Frist fest.
  4. Wiederhole die Anfrage oder starte einen neuen Turn. Prüfe bei einem HTTP-Fehler das Ergebnis des ursprünglichen Vorgangs, bevor du ihn wiederholst. Ist ein Turn fehlgeschlagen, warte, bis die Sitzung den Status idle hat. Sende dann eine weitere Nachricht und bitte den Agenten, nur die noch ausstehende Arbeit fortzusetzen. Damit startet ein neuer Turn in der bestehenden Unterhaltung.

Prüfe die Tool-Ergebnisse auch dann, wenn der Turn erfolgreich abgeschlossen wurde. Beende automatische Wiederholungen, wenn sich der Fehler ändert oder die Höchstzahl an Versuchen erreicht ist.

Ungültige Eingaben korrigieren

Korrigiere das in error.param oder error.message angegebene Feld, bevor du die Anfrage erneut sendest.

Verkleinere bei Größenfehlern das Eingabe- und Ausgabeschema oder das Tool-Ergebnis, bevor du es erneut versuchst. Ist die Agentenkonfiguration zu groß, erstelle eine neue Sitzung mit kürzeren Anweisungen und kompakteren Tool-Definitionen.

Anforderungen und Beispiele für Uploads findest du im Abschnitt Upload-Fehler beheben. Weist die Meldung auf ein Problem mit einem Bild hin, prüfe die Bilddaten oder die URL.

Unterbrochene Streams

Nach einem error-Ereignis oder einem Verbindungsabbruch beim Stream ist der endgültige Zustand des Turns noch unklar. Folge der Anleitung zum Wiederherstellen eines unterbrochenen Streams, um die Verbindung wiederherzustellen und die gespeicherte Arbeit zu prüfen, bevor du die Eingabe erneut sendest. Enthält die abgerufene Sitzung status: "failed" oder empfängst du agent.session.failed, beende die Verbindungsversuche und folge den Hinweisen zur Wiederherstellung bei Sitzungsfehlern.

Gib bei anhaltenden Fehlern in deiner Supportanfrage die Anfrage-ID, die Sitzungs-ID und die Turn-ID an.