API-Fehler

Auf dieser Seite finden Sie eine Referenz für alle Fehlercodes der Interactions API, eine Beschreibung des Formats von Fehlerantworten 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 beheben.

Code HTTP-Status Beschreibung Empfohlene Maßnahmen
invalid_request 400 Fehlerhafte Anfrage Die Anfragenutzlast ist fehlerhaft oder enthält ungültige Parameter. Prüfen Sie die Syntax und die Parameter Ihrer Anfrage anhand der API-Referenz.
failed_precondition 400 Fehlerhafte Anfrage Die Anfrage kann nicht verarbeitet werden, weil eine Voraussetzung nicht erfüllt ist (z. B. deaktivierte Abrechnung). Prüfen Sie den Abrechnungsstatus des Projekts oder die Kontovoraussetzungen.
out_of_range 416 Angeforderter Bereich nicht erfüllbar Der Anfrageparameter liegt außerhalb des gültigen Bereichs. Prüfen Sie die Parameterwerte und Limits.
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, ist ungültig oder abgelaufen. Prüfen Sie Ihren API-Schlüssel.
payment_required 402 Payment Required Ihr Vorauszahlungsguthaben ist aufgebraucht. Fügen Sie Ihrem Rechnungskonto Guthaben hinzu oder aktivieren Sie das automatische Aufladen. Versuchen Sie es nicht noch einmal: Die Anfrage wird erst erfolgreich sein, wenn Guthaben hinzugefügt wurde.
permission_denied 403 Verboten Ihr API-Schlüssel ist nicht für diese Ressource berechtigt oder der API-Zugriff Ihres Projekts ist eingeschränkt. Prüfen Sie die Berechtigungen Ihres API-Schlüssels, die Berechtigung für die Projektstufe und den Abrechnungsstatus. Weitere Informationen finden Sie unter Fehlerbehebung bei eingeschränkten oder nicht verfügbaren Projekten.
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 verwenden Sie ein anderes Modell.
already_exists 409-Fehler – Konflikt Das Entität, die Sie erstellen möchten, existiert bereits. Prüfen Sie, ob die Ressource bereits vorhanden ist, bevor Sie sie neu erstellen.
aborted 409-Fehler – Konflikt Der Vorgang wurde aufgrund eines Konflikts oder einer fehlgeschlagenen Nebenläufigkeitsprüfung abgebrochen. Wiederholen Sie die Anfrage auf einer höheren Anwendungsebene.
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.
too_many_requests 429 Zu viele Anfragen Sie haben innerhalb kurzer Zeit zu viele Anfragen gestellt. Warten Sie und wiederholen Sie den Vorgang mit exponentiellem Backoff.
cancelled 499 Client Closed Request Der Client hat die Anfrage abgebrochen, bevor sie abgeschlossen wurde. Es sind keine Maßnahmen erforderlich. Das bedeutet in der Regel, dass die Verbindung zum Client getrennt wurde.
api_error 500 Interner Serverfehler Auf dem Server ist ein unerwarteter Fehler aufgetreten. Wiederholen Sie die Anfrage. Sollte das Problem weiterhin auftreten, wenden Sie sich an den Support.
unimplemented 501 Nicht implementiert Der Vorgang oder die Funktion ist nicht implementiert oder wird nicht unterstützt. Prüfen Sie die API-Funktionen oder wechseln Sie zu einer unterstützten Funktion.
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.
deadline_exceeded 504 Gateway-Zeitüberschreitung Die Anfrage wurde nicht innerhalb der Frist abgeschlossen. Entfernen oder erhöhen Sie die Einstellung für die Client-Frist, um die Server-Standardeinstellung zu verwenden.

Codes für blockierte Generierung

Diese Fehlercodes weisen darauf hin, dass die Ausgabe des Modells aufgrund von Richtlinien-, Sicherheits- oder Inhaltsbeschränkungen blockiert wurde. 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 Die Anfrage wurde aufgrund von Urheberrechts- oder Rezitationsbeschränkungen blockiert.
language Die Anfrage wurde aufgrund einer nicht unterstützten Sprache blockiert.
prohibited_content Die Anfrage wurde aufgrund der Richtlinien für unzulässige Inhalte blockiert.
spii Die Anfrage wurde aufgrund von Einschränkungen für vertrauliche personenidentifizierbare Informationen blockiert.
blocklist Unzulässige Begriffe auf einer Sperrliste haben die Anfrage blockiert.
image_safety Die Bildgenerierung wurde aufgrund von Sicherheitsverstößen blockiert.
image_prohibited_content Die Richtlinien zu unzulässigen Inhalten haben die Bildgenerierung blockiert.
image_recitation Die Bildgenerierung wurde aufgrund von Urheberrechts- oder Rezitationsbeschränkungen blockiert.
image_other Die Bildgenerierung wurde aus nicht angegebenen Gründen blockiert.
content_blocked Die Anfrage wurde aus einem nicht angegebenen Richtliniengrund blockiert.

Fehlercodes bei der 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 nicht in der Anfrage 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 zurück, das einen code und eine message enthält. 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 menschenlesbare Beschreibung des Fehlers.

Wie Fehler gemeldet werden

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

Standard-HTTP-Anfragen

Bei Standardanfragen (Nicht-Streaming-Anfragen) legt die API den HTTP-Antwortstatuscode (z. B. 400 Bad Request, 401 Unauthorized oder 429 Too Many Requests) fest 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]'."
  }
}

Streaming-Anfragen (SSE)

Bei Streaminganfragen (stream: true) sendet die API Fehlerereignisse über den SSE-Stream (Server-Sent Events), wobei event_type auf "error" gesetzt ist. Das Feld error 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