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 Berechtigungen für Ihren API-Schlüssel 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 pro 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 die Ausgabe des Modells aufgrund von Richtlinien-, Sicherheits- oder Inhaltseinschränkungen blockiert wurde. Wenn Sie einen dieser Codes erhalten, ändern Sie Ihre Eingabe und versuchen Sie es noch einmal.

Code Beschreibung
safety Die Anfrage wurde aufgrund von Sicherheitsverstößen (schädliche Inhalte) blockiert.
recitation Die Anfrage wurde aufgrund von Einschränkungen in Bezug auf Urheberrechte oder Rezitation blockiert.
language Die Anfrage wurde aufgrund einer nicht unterstützten Sprache blockiert.
prohibited_content Die Anfrage wurde aufgrund von Richtlinien für unzulässige Inhalte blockiert.
spii Die Anfrage wurde aufgrund von Einschränkungen in Bezug auf vertrauliche personenidentifizierbare Informationen blockiert.
blocklist Die Anfrage wurde aufgrund von unzulässigen Begriffen auf einer Blockliste blockiert.
image_safety Die Bildgenerierung wurde aufgrund von Sicherheitsverstößen blockiert.
image_prohibited_content Die Bildgenerierung wurde aufgrund von Richtlinien für unzulässige Inhalte blockiert.
image_recitation Die Bildgenerierung wurde aufgrund von Einschränkungen in Bezug auf Urheberrechte oder Rezitation blockiert.
image_other Die Bildgenerierung wurde aus nicht näher bestimmten Gründen blockiert.
content_blocked Die Anfrage wurde aufgrund einer nicht näher bestimmten Richtlinie blockiert.

Fehlercodes für die Generierung

Diese Fehlercodes weisen auf ein strukturelles Problem mit der generierten Ausgabe des Modells hin, z. B. ein fehlerhafter Funktionsaufruf oder ein nicht deklarierter 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 im snake_case-Format.
message String Eine für Menschen lesbare Beschreibung des Fehlers.

Fehlerübermittlung

Die API liefert Fehler 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 Referenz zur Interactions API.

Nächste Schritte