API-Fehler

Auf dieser Seite finden Sie eine Referenz für alle Fehlercodes der Interactions API, eine Beschreibung des Formats der Fehlerantwort und eine Erläuterung, wie die API Fehler für verschiedene Anfragetypen liefert.

Standard-API-Fehlercodes

Diese allgemeinen Fehlercodes auf Anfrageebene entsprechen den Standard-HTTP-Statuscodes. Verwenden Sie das Feld code in Ihrer Anwendungslogik, um Fehler programmatisch zu verarbeiten.

Code HTTP-Status Beschreibung Empfohlene Maßnahmen
invalid_request 400 Fehlerhafte Anfrage Die Anfrage ist fehlerhaft oder enthält ungültige Parameter. Vergleichen Sie Ihre Eingaben mit der API-Referenz.
parameter_unknown 400 Fehlerhafte Anfrage Die Anfrage enthält einen unbekannten Parameter. Entfernen Sie den nicht erkannten Parameter und versuchen Sie es noch einmal.
authentication 401 Nicht autorisiert Der API-Schlüssel fehlt oder ist ungültig. Prüfen Sie Ihren API-Schlüssel.
permission_denied 403 Verboten Ihr API-Schlüssel hat keine Berechtigung für diese Ressource. Prüfen Sie die API-Schlüsselberechtigungen und den Projektzugriff.
not_found 404 Nicht gefunden Die angeforderte Ressource wurde nicht gefunden. Prüfen Sie den Ressourcenpfad und die Parameter.
model_not_found 404 Nicht gefunden Das angegebene Modell wurde nicht gefunden. Prüfen Sie den Modellnamen oder wechseln Sie zu einem anderen Modell.
rate_limit_exceeded 429 Zu viele Anfragen Sie haben das Limit für Anfragen oder Tokens pro Minute oder Sekunde überschritten. Warten Sie und wiederholen Sie den Vorgang mit exponentiellem Backoff.
quota_exceeded 429 Zu viele Anfragen Sie haben Ihr Tageskontingent überschritten. Warten Sie, bis das Kontingent zurückgesetzt wird, oder fordern Sie eine Kontingenterhöhung an.
cancelled 499 Client Closed Request Der Client hat die Anfrage abgebrochen, bevor sie abgeschlossen wurde. Es sind keine Maßnahmen erforderlich. In der Regel bedeutet dies, dass die Verbindung zum Client getrennt wurde.
api_error 500 Interner Serverfehler Auf dem Server ist ein unerwarteter Fehler aufgetreten. Wiederholen Sie die Anfrage. Wenn das Problem weiterhin besteht, wenden Sie sich an den Support.
service_unavailable 503 Dienst nicht verfügbar Der Dienst ist vorübergehend überlastet oder nicht verfügbar. Warten Sie und wiederholen Sie den Vorgang mit exponentiellem Backoff.

Codes für blockierte Generierung

Diese Fehlercodes geben an, dass Richtlinien-, Sicherheits- oder Inhaltsbeschränkungen die Ausgabe des Modells blockiert haben. Wenn Sie einen dieser Codes erhalten, ändern Sie Ihre Eingabe und versuchen Sie es noch einmal.

Code Beschreibung
safety Sicherheitsverstöße (schädliche Inhalte) haben die Anfrage blockiert.
recitation Beschränkungen aufgrund von Urheberrechten oder Vorträgen haben die Anfrage blockiert.
language Eine nicht unterstützte Sprache hat die Anfrage blockiert.
prohibited_content Richtlinien für unzulässige Inhalte haben die Anfrage blockiert.
spii Beschränkungen für vertrauliche personenidentifizierbare Informationen haben die Anfrage blockiert.
blocklist Unzulässige Begriffe auf einer Blockliste haben die Anfrage blockiert.
image_safety Sicherheitsverstöße haben die Bildgenerierung blockiert.
image_prohibited_content Richtlinien für unzulässige Inhalte haben die Bildgenerierung blockiert.
image_recitation Beschränkungen aufgrund von Urheberrechten oder Vorträgen haben die Bildgenerierung blockiert.
image_other Nicht angegebene Gründe haben die Bildgenerierung blockiert.
content_blocked Ein nicht angegebener Richtliniengrund hat die Anfrage blockiert.

Fehlercodes für die Generierung

Diese Fehlercodes weisen auf ein strukturelles Problem mit der generierten Ausgabe des Modells hin, z. B. einen fehlerhaften Funktionsaufruf oder einen nicht deklarierten Toolaufruf.

Code Beschreibung
malformed_function_call Das Modell hat einen Funktionsaufruf erzeugt, der nicht geparst werden konnte.
malformed_tool_call Das Modell hat einen Toolaufruf erzeugt, der nicht geparst werden konnte.
unexpected_tool_call Das Modell hat ein Tool aufgerufen, das in der Anfrage nicht deklariert wurde.
no_image Das Modell konnte kein Bild generieren.
too_many_tool_calls Das Modell hat mehr Toolaufrufe generiert als zulässig.
missing_thought_signature In der Antwort fehlt eine erforderliche Gedankensignatur.

Format der Fehlerantwort

Alle Fehler der Interactions API geben ein error-Objekt mit einem code und message zurück. Wenn Sie beispielsweise einen nicht unterstützten Tooltyp übergeben, wird Folgendes zurückgegeben:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Feld Typ Beschreibung
code String Ein maschinenlesbarer Fehlercode in snake_case.
message String Eine für Menschen lesbare Beschreibung des Fehlers.

Fehlerübermittlung

Die API liefert Fehler unterschiedlich, je nachdem, ob Sie eine Standard-HTTP-Anfrage oder eine Streaminganfrage (SSE) stellen.

Standard-HTTP-Anfragen

Bei Standardanfragen (ohne Streaming) legt die API den HTTP-Antwortstatuscode fest (z. B. 400 Bad Request, 401 Unauthorized oder 429 Too Many Requests) und gibt ein error-Objekt im JSON-Antworttext zurück:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Streaminganfragen (SSE)

Bei Streaminganfragen (stream: true) sendet die API Fehlerereignisse über den SSE-Stream (Server-Sent Events), wobei event_type auf "error" gesetzt ist. Das error Feld enthält dieselbe code und message Struktur:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Das vollständige SSE-Ereignisschema finden Sie in der Interactions API-Referenz.

Nächste Schritte