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.
- 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.
- 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.
- Warte und begrenze die Anzahl der Versuche. Folge den allgemeinen Hinweisen zu erneuten Versuchen. Halte die in
Retry-Afterangegebene Wartezeit aus der HTTP-Antwort ein und lege eine Höchstzahl an Versuchen oder eine Frist fest. - 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
idlehat. 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.