Gemini 4 API: Fehler bei Carbon, Neon und Hydrogen finden und beheben

Fehler der Gemini 4 API bei Carbon, Neon und Hydrogen diagnostizieren: falsche Modell-IDs, fehlende Bezahlstufe, 429, Thinking-Level, leere Antworten, Tool-Calls und Sicherheitsblockaden.

Strichzeichnung eines geöffneten Sicherungskastens mit zwei Reihen Schaltern; einer davon, orange, hat ausgelöst.

Die meisten Fehler der Gemini 4 API fallen in fünf Gruppen: falsche Modell-ID oder Route, die Stufe des Projekts (Carbon und Neon gibt es nur in der kostenpflichtigen Stufe), Kontingent (429), nicht unterstützte Parameter (minimal oder xhigh bei Carbon) und Antworten, die formal erfolgreich sind, aber keine Antwort enthalten, weil Thinking max_output_tokens aufgebraucht hat. Welche Gruppe vorliegt, erkennen Sie am HTTP-Status, am code des Fehlers und an der Struktur der Antwort. Ein neuer API-Key hilft nur in einem engen Fall: wenn der Key geleakt oder gesperrt wurde.

Dieser Leitfaden behandelt Gemini 4 Carbon, Neon und Hydrogen. Für Argon gibt es einen eigenen Artikel, die Fehleranalyse für die Gemini 4 Argon API; dessen Vorlage für Störungsberichte und synthetische Testfälle wiederholen wir hier nicht. Die Angaben zu Google stammen aus der Gemini-API-Dokumentation, geprüft am 19. November 2026 (die verlinkten Google-Dokumente sind englischsprachig). Die Ofox-Ergebnisse stammen aus 21 echten Anfragen, die wir am selben Tag über Ofox an google/gemini-4-hydrogen und google/gemini-4-argon geschickt haben, ein Durchlauf pro Fall (geschätzte Gesamtkosten unter 0,05 US-Dollar). Carbon und Neon sind auf Ofox nicht verfügbar (Katalog geprüft am 19. November 2026), daher nutzen alle Carbon- und Neon-Beispiele hier die native API von Google.

Dieser Artikel wird von Ofox veröffentlicht. Weicht ein Ergebnis über das Gateway von der Google-Dokumentation ab, zeigen wir beides und stellen die Abweichung nicht als Regel für Googles eigenen Endpunkt dar.

Zuerst nach dem Symptom diagnostizieren

Nehmen Sie die erste passende Zeile. Jede Zeile verweist auf den Abschnitt mit der Lösung und dem Prüfschritt.

Was Sie sehenWahrscheinlichste UrsacheZuerst prüfenAbschnitt
404 model_not_foundTippfehler, erfundenes Suffix oder ein Modell, das Ihre Route nicht anbietetID aus der aktuellen Modellliste des Anbieters kopierenModell-ID
403 PERMISSION_DENIED mit Hinweis auf Verifizierung, kostenlose Stufe oder ZahlungStufe des Projekts oder AbrechnungsstatusProjektstatus in AI Studio, nicht den KeyBezahlstufe
402 payment_requiredPrepaid-Guthaben aufgebrauchtGuthaben; nicht wiederholenBezahlstufe
429 mit rate_limit_exceeded / too_many_requestsLastspitze innerhalb einer MinuteParallelität und Token-Rate429
429 mit quota_exceededTageskontingent aufgebrauchtAuf den Reset warten; Wiederholungen helfen nicht429
400 mit Hinweis auf thinking_levelLevel für dieses Modell ungültigLevel-Tabelle pro ModellThinking-Level
400 nach der Migration von Gemini 3.xAlte Sampling-, Caching- oder Tool-Prompting-KonfigurationMigrations-ChecklisteMigration
HTTP 200, leerer Text, MAX_TOKENS / length / incompleteThinking hat das Ausgabebudget verbrauchtmax_output_tokens und thinking_levelAusgabebudget
Status requires_continuationEin Vordergrund-Schritt hat sein Limit pro Anfrage erreichtSDK-Version oder FortsetzungsschleifeAusgabebudget
Hintergrundjob failed oder hängtServerseitiger Fehler, 24-Stunden-Limit oder store=falseStatus der Interaction und Liste errorsHintergrund
missing_thought_signature, malformed_function_callTool-Verlauf verändert oder Tools nicht deklariertWie der Verlauf erneut gesendet wirdTool-Calls
400 mit Code safety, prohibited_contentInhaltsfilterPrompt und Ihre SicherheitseinstellungenSicherheit

Erst die Fehlerstruktur lesen, dann die Meldung

Google und ein Gateway wie Ofox formatieren Fehler unterschiedlich. Prüfen Sie, wer geantwortet hat, bevor Sie auf den Text reagieren.

Googles Interactions API liefert ein error-Objekt mit einem maschinenlesbaren code und einer message, laut Googles Referenz zu API-Fehlern:

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

Beim Streaming kommt dasselbe Objekt als SSE-Event mit "event_type": "error" an. Ein Stream kann mit HTTP 200 beginnen und trotzdem später fehlschlagen; Ihr Stream-Reader muss also Error-Events verarbeiten. Die ältere generateContent-API nutzt den früheren Google-RPC-Stil mit Status wie INVALID_ARGUMENT und RESOURCE_EXHAUSTED. Deshalb tauchen auf Googles Troubleshooting-Seiten beide Benennungen auf.

Das Ofox-Gateway lieferte in unseren Tests zwei Strukturen. Stand die Modell-ID nicht im Katalog des Gateways, antwortete das Gateway mit einem eigenen Fehler-Body (Request-ID gekürzt). Das Meldungsformat entspricht der Zeile zur falsch geschriebenen ID im Gemini-Leitfaden von Ofox:

{"error": {"message": "Model 'google/gemini-4-carbon' not found",
           "type": "model_not_found", "code": 404, "request_id": "e0925435-..."}}

Erreichte die Anfrage die Google-Seite (Ofox stellt Gemini laut Gemini-Leitfaden von Ofox über Vertex AI bereit) und wurde dort abgelehnt, kam der Upstream-Text innerhalb der Gateway-Hülle zurück:

{"error": {"code": null,
  "message": "Invalid value at 'generation_config.thinking_config.thinking_level' (type.googleapis.com/google.cloud.aiplatform.v1.GenerationConfig.ThinkingConfig.ThinkingLevel),",
  "param": null, "request_id": "1439e1a1-...", "type": "INVALID_ARGUMENT"}}

Ein Typname google.cloud.aiplatform in der Meldung zeigt, dass der Upstream-Modelldienst den Wert abgelehnt hat. Die Meldung Model '<id>' not found bedeutet, dass das Gateway die Modell-ID nicht erkannt hat.

Der Ofox-Leitfaden zur Fehlerbehandlung dokumentiert die Statuscodes und welche davon wiederholt werden dürfen. Sein Beispiel-Fehler-Body enthält "code": "invalid_api_key" und "type": "authentication_error", und seine Tabelle nennt als Typ für 404 not_found_error. Die Bodies, die wir am 19. November 2026 erhielten, waren anders aufgebaut: Der 401 hatte "code": 401 und "type": "invalid_api_key", die 404er hatten "code": 404 und "type": "model_not_found". Wenn Ihr Handler nach diesen Feldern verzweigt, prüfen Sie sowohl code als auch type und testen Sie ihn mit einem Fehler, den Sie auf Ihrer eigenen Route mitgeschnitten haben.

404 model not found: ID oder Route stimmt nicht

Symptom. Google: 404 mit Code model_not_found. Ofox: 404 mit Typ model_not_found und der Meldung Model '<id>' not found.

Ursache. Die vier Gemini-4-IDs in Googles API lauten exakt gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen und gemini-4-argon (Modellseite). Keine hat ein Suffix -preview oder -latest. Die andere häufige Ursache ist eine Route, die das Modell gar nicht anbietet.

Unsere Ofox-Anfragen am 19. November 2026 (je ein Durchlauf):

Gesendeter Modell-StringEndpunktErgebnis
google/gemini-4-hydrogen-preview/v1/chat/completions404 model_not_found
google/gemini-4-hydrogen-preview/gemini/v1beta/models/...:generateContent404 model_not_found
google/gemini-4-carbon/v1/chat/completions404 model_not_found
google/gemini-4-neon/v1/chat/completions404 model_not_found
gemini-4-hydrogen (ohne Präfix google/)/v1/chat/completions200, Feld model in der Antwort: google/gemini-4-hydrogen

Lösung. Bei Google verwenden Sie die ID ohne Präfix. Bei Ofox verwenden Sie google/gemini-4-hydrogen oder google/gemini-4-argon. Die Form ohne Präfix wurde in unserem Test ebenfalls aufgelöst, und laut Gemini-Leitfaden von Ofox ist das Präfix optional. Für Carbon oder Neon nutzen Sie ein Google-Projekt in der kostenpflichtigen Stufe. Eine andere Schreibweise lässt kein Modell auftauchen, das ein Gateway nicht listet.

Prüfen. Listen Sie die Modelle über denselben Endpunkt und mit demselben Key ab, den Ihre App nutzt: GET https://generativelanguage.googleapis.com/v1beta/models bei Google oder GET https://api.ofox.io/v1/models bei Ofox. Google weist darauf hin, dass models.list nur prüft, ob der Key existiert. Ein 200 vom Listen-Endpunkt beweist nicht, dass Inferenz für das Projekt freigeschaltet ist; bestätigen Sie das mit einem kleinen Generierungsaufruf.

Carbon und Neon scheitern in einem Projekt der kostenlosen Stufe

Symptom. Eine Anfrage, die mit Hydrogen funktioniert, schlägt fehl, sobald Sie das Modell auf Carbon oder Neon umstellen. Typische Anzeichen sind ein 403 PERMISSION_DENIED, der Projektstatus Free tier unavailable oder Payment needed in AI Studio oder ein Kontingentfehler in einem Projekt, für das nie eine Abrechnung eingerichtet wurde.

Ursache. Im Carbon-Leitfaden heißt es, Carbon “is not available on the Free tier” (in der kostenlosen Stufe nicht verfügbar). Im Neon-Leitfaden steht, Neon sei “available on the paid tier only” (nur in der kostenpflichtigen Stufe verfügbar). Hydrogen ist das einzige Gemini-4-Modell mit kostenloser Stufe (Preise). Google veröffentlicht keine modellspezifische Fehlermeldung für ein Projekt der kostenlosen Stufe, das Carbon oder Neon aufruft; gleichen Sie also nicht auf exakten Text ab. Werten Sie den Status aus und prüfen Sie dann das Projekt.

Googles Troubleshooting-Leitfaden führt die 403-Varianten auf Projektebene auf:

SignalBedeutungLösung
403 mit FREE_TIER_VERIFICATION_REQUIRED, Status Verification neededProjekt der kostenlosen Stufe muss verifiziert werdenMit einem Mobilgerät verifizieren oder Abrechnung einrichten
Status Free tier unavailableProjekt ist für die kostenlose Stufe nicht berechtigtAktives Cloud-Billing-Konto verknüpfen
Status Payment needed oder 403 mit Hinweis auf offenen SaldoRechnungskonto im RückstandSaldo ausgleichen; der Zugriff kehrt automatisch zurück
403 mit der Meldung, der Key sei als geleakt gemeldetGoogle hat den Key gesperrtNeuen Key erstellen und aus Client-Code heraushalten
402 payment_requiredPrepaid-Guthaben aufgebrauchtGuthaben aufladen oder automatische Aufladung aktivieren; nicht wiederholen

Zwei Details sorgen oft für Ärger. Die Berechtigung wird pro Google-Cloud-Projekt geprüft, ein anderer Key aus demselben Projekt liefert also dasselbe Ergebnis. Außerdem schaltet der Wechsel in die kostenpflichtige Stufe kein Kontingent der kostenlosen Stufe frei; bezahlte Nutzung wird abgerechnet. Für einen 429 in der kostenlosen Stufe mit Limit 0 erklärt die Diagnose für Limit 0 im Gemini Free Tier (Englisch), wie Sie die Kontingentmetrik lesen. Sie wurde für Bildmodelle geschrieben, die Projektprüfung ist aber dieselbe. Was die kostenlose Stufe von Hydrogen umfasst, beschreibt der Leitfaden zum kostenlosen Tarif der Gemini 4 API.

Prüfen. Öffnen Sie in AI Studio das Projekt, dem der Key gehört, und bestätigen Sie die Stufe. Senden Sie dann eine kurze Carbon- oder Neon-Anfrage. Die Preise für Carbon und Argon verdoppeln sich am 1. Dezember 2026 (Carbon-Leitfaden); die Zahlen stehen in der Analyse der Preisänderung zum Dezember.

429: Lastspitze von erschöpftem Kontingent unterscheiden

Symptom. HTTP 429. In der Interactions API lautet der Code rate_limit_exceeded, too_many_requests oder quota_exceeded. Bei generateContent ist es RESOURCE_EXHAUSTED.

Ursache. Googles Seite zu Rate Limits legt drei Punkte fest:

  • Limits gelten pro Projekt, nicht pro API-Key.
  • Tageskontingente für Anfragen werden um Mitternacht pazifischer Zeit zurückgesetzt.
  • Bezahlte Projekte haben zusätzlich ein ausgabenbasiertes Limit in einem gleitenden 10-Minuten-Fenster: 10 US-Dollar in Tier 1 und 200 US-Dollar in Tier 2 und 3. Wird es überschritten, kommt 429 RESOURCE_EXHAUSTED, auch wenn Ihre Anfragerate niedrig ist.

Das Ausgabenlimit wird bei Gemini 4 leicht übersehen. Neon und Hydrogen nutzen standardmäßig Thinking auf high, und Thinking-Tokens werden als Output-Tokens abgerechnet. Schon wenige lange Anfragen mit hohem Thinking-Aufwand können das Ausgabenfenster von Tier 1 ausschöpfen, ohne ein einziges RPM-Limit zu überschreiten.

Lösung. Richten Sie die Maßnahme nach dem Code aus:

CodeTunNicht tun
rate_limit_exceeded, too_many_requestsExponentielles Backoff mit Jitter; Parallelität senkenSofort parallel wiederholen
quota_exceededJob bis zum Reset pausieren oder mehr Kontingent beantragenDas Retry-Budget an einem Tageskontingent verbrennen
Ausgabenbasiertes RESOURCE_EXHAUSTEDTeure Aufrufe zeitlich verteilen; thinking_level oder Ausgabegröße senkenAnnehmen, es gehe um das RPM-Limit

Googles Python-SDK wiederholt 429 und 5xx bereits bis zu viermal, beginnend bei etwa 1 Sekunde mit einer Obergrenze von 60 Sekunden (Troubleshooting). Legen Sie eine eigene Retry-Schleife darum, kann aus einem Fehler ein Dutzend Anfragen oder mehr werden. Überlassen Sie Wiederholungen einer einzigen Schicht. Der allgemeine Leitfaden zu 429-Wiederholungen (Englisch) behandelt Header und Backoff-Timing, und Fehlerbehandlung für AI-APIs (Englisch) enthält Code für Backoff und Circuit Breaker.

Bei Ofox. Ein 429 des Gateways (Typ rate_limit_error im Leitfaden zur Fehlerbehandlung) ist ein eigenes Limit, getrennt vom Google-Projektkontingent. Die Ofox-Dokumentation zu Rate Limits nennt einen Standardwert von 100 RPM, gezählt über alle Keys eines Teams (erneut geprüft am 19. November 2026). Ein höheres Limit können Sie per E-Mail bei Ofox anfragen, wie auf dieser Seite beschrieben. In unseren Tests haben wir keinen 429 ausgelöst.

Prüfen. Protokollieren Sie bei jedem 429 den genauen code. Taucht quota_exceeded nach Einführung von Backoff weiter auf, liegt das Problem beim Kontingent, nicht an der Lastverteilung.

Thinking-Level-Fehler: minimal und xhigh

Die Gemini-4-Modelle unterstützen nicht dieselben Thinking-Level. Googles Thinking-Leitfaden führt auf:

ModellStandardUnterstützte Level
gemini-4-carbonmediumlow, medium, high
gemini-4-argonmediumlow, medium, high
gemini-4-neonhighlow, medium, high, xhigh
gemini-4-hydrogenhighlow, medium, high, xhigh

minimal wird von keinem Gemini-4-Modell unterstützt. Laut den Migrations-Checklisten für Neon und Hydrogen lehnen beide Modelle minimal mit einem Fehler ab. Googles Thinking-Leitfaden führt minimal auch bei gemini-3.8-flash als nicht unterstützt; eine Konfiguration, die von einem älteren Modell übernommen wurde, das den Wert akzeptierte, muss also genauso angepasst werden. Laut Google ist bei Carbon und Argon high das Maximum, die genaue Fehlermeldung für xhigh auf diesen Modellen veröffentlicht Google aber nicht.

Lösung. Ordnen Sie alte Einstellungen explizit zu: Aus minimal wird low, und bei Carbon und Argon wird aus xhigh high. Validieren Sie das Level im eigenen Code anhand der Modell-ID, bevor Sie senden.

Was das Gateway tat. Unsere Ofox-Tests zeigen, warum Sie sich nicht darauf verlassen sollten, dass der Server das abfängt:

Anfrage (Ofox, 2026-11-19, je ein Durchlauf)Ergebnis
Hydrogen, Chat Completions reasoning_effort: "minimal"200, kein Fehler; 20 Reasoning-Tokens
Hydrogen, nativ thinkingLevel: "minimal"200, kein Fehler; 22 Thinking-Tokens
Argon, Chat Completions reasoning_effort: "xhigh"200, kein Fehler; 157 Reasoning-Tokens
Argon, nativ thinkingLevel: "xhigh"200, kein Fehler; 131 Thinking-Tokens
Hydrogen, reasoning_effort: "banana"400 INVALID_ARGUMENT (siehe oben)

Die Werte, die Google als ungültig dokumentiert, wurden ohne Fehler angenommen, aber das heißt nicht, dass sie gewirkt haben. Nichts in den Antworten zeigt, welches Level angewendet wurde. Das Gateway hat den Wert möglicherweise verworfen oder auf einen unterstützten abgebildet. Beim selben Prompt verbrauchten Hydrogen-Durchläufe ohne Thinking-Einstellung zwischen 22 und 82 Thinking-Tokens, die beiden minimal-Durchläufe 20 und 22; die Token-Zahlen einzelner Durchläufe sagen also nicht, was passiert ist. Für Argon haben wir überhaupt keinen Vergleichslauf gemacht. Ein frei erfundener Wert wurde upstream abgelehnt. Betrachten Sie das als einzelne Beobachtung auf einer Route an einem Tag. Verlassen Sie sich nicht darauf: Code, der minimal sendet, weil das Gateway es akzeptiert hat, kann beim direkten Aufruf von Google brechen. Der Gemini-Thinking-Leitfaden von Ofox dokumentiert die Felder thinkingLevel und reasoning_effort. Wie Sie ein Level passend zur Aufgabe wählen, steht in Gemini 4 Thinking-Level.

Leere oder abgeschnittene Antworten: das gemeinsame 1M-Fenster

Symptom. HTTP 200, aber der Text ist leer oder abgeschnitten. Natives generateContent zeigt finishReason: "MAX_TOKENS", Chat Completions zeigt finish_reason: "length", und eine Interactions-Ressource zeigt den Status incomplete.

Ursache. In Gemini 4 begrenzt max_output_tokens Thinking und sichtbare Ausgabe zusammen. Googles Leitfaden zu langen Ausgaben beschreibt genau dieses Symptom: Status incomplete mit leerem Text bedeutet “the model used all tokens on thinking.” (das Modell hat alle Tokens für Thinking verbraucht). Ein aus einer älteren App übernommenes Limit wie 8.192 macht das deutlich wahrscheinlicher, besonders bei Neon und Hydrogen, die standardmäßig auf high stehen.

Wir haben das auf Hydrogen über Ofox mit einer einzeiligen Rechenfrage reproduziert:

RouteEinstellungErgebnis
Chat Completionsmax_tokens: 16200, content: "", finish_reason: "length", 13 von 16 Completion-Tokens waren Reasoning
Natives generateContentmaxOutputTokens: 16200, Candidate ohne parts, finishReason: "MAX_TOKENS", thoughtsTokenCount: 13

Die Anfrage ist nicht fehlgeschlagen und wurde abgerechnet. Nur die Antwort fehlt. Prüft Ihre App allein den HTTP-Status, meldet sie Erfolg, obwohl keine Antwort da ist.

Lösung.

  • Entfernen Sie niedrige, fest eingetragene Limits. Google empfiehlt für Carbon mindestens 32.768. Bei Neon und Hydrogen behalten Sie den Standardwert 65.536 oder lassen das Feld weg.
  • Um weniger Tokens zu verbrauchen, senken Sie thinking_level. Laut Googles Leitfaden zu langen Ausgaben lässt ein niedrigeres max_output_tokens das Modell nicht knapper denken; es schneidet die Antwort nur früher ab.
  • Für Ausgaben über 64K Tokens setzen Sie background: true und max_output_tokens über 65.536, höchstens auf 1.048.576 minus Ihre Input-Tokens.

Grenzen des gemeinsamen Fensters. Input, Thinking und Ausgabe teilen sich ein Fenster von 1.048.576 Tokens. Übersteigen bei Google Input plus max_output_tokens das Fenster, kappt die API das Ausgabelimit auf den verbleibenden Platz, statt die Anfrage abzulehnen (Thinking-Leitfaden). Unsere Ofox-Anfragen mit max_tokens: 2000000 (Chat Completions) und maxOutputTokens: 2000000 (nativ) wurden beide ohne Fehler angenommen und normal beantwortet; welches Limit tatsächlich galt, zeigt die Antwort nicht. Ein Input, der allein das Fenster überschreitet, ist ein harter Fehler. Der Gemini-Leitfaden von Ofox nennt dafür 400 INVALID_ARGUMENT mit der Meldung The input token count exceeds the maximum number of tokens allowed 1048576. Diesen Fall haben wir nicht reproduziert, weil ein Test-Input mit einer Million Tokens unser Testbudget überschritten hätte.

Limits pro Schritt. Ein einzelner Vordergrund-Schritt (Hop) ist bei Neon und Hydrogen auf 65.536 Tokens begrenzt, bei Nicht-Streaming-Aufrufen auf Carbon und Argon jedoch auf 32.768. Erreicht ein Schritt sein Limit, während noch Budget übrig ist, lautet der Status requires_continuation. SDKs älter als Python 2.34.0, JavaScript 2.32.0, Go 1.77.0, Java 1.80.0 und .NET 1.28.0 setzen Vordergrund-Interactions nicht automatisch fort. Aktualisieren Sie oder senden Sie den nächsten Schritt mit previous_interaction_id und continuation_token.

Prüfen. Jede Antwortprüfung sollte das Abschlusssignal (status == "completed", finishReason == "STOP" oder finish_reason == "stop") und einen nicht leeren Text testen, nicht nur den HTTP-Status.

Hintergrundausführung und lang laufende Interactions

Lange Carbon- und Neon-Jobs gehören in die Hintergrundausführung. Googles Leitfaden zur Hintergrundausführung und der Leitfaden zu langen Ausgaben dokumentieren diese Fehler:

SymptomUrsacheLösung
400 beim Anlegenbackground: true zusammen mit store: falseFür Hintergrundjobs store: true (Standard) beibehalten
400 beim Anhängen einer FolgerundeDie vorherige Interaction ist noch in_progressAuf completed warten, bevor ihre ID als previous_interaction_id übergeben wird
Status failedFehler während der Ausführung (Googles Beispiele: ein Tool-Fehler, Rate Limits) oder der Job lief länger als 24 StundenEinmal wiederholen; schlägt er erneut fehl, die Interaction-ID an den Support senden
Status failed mit Sicherheitscode in errorsInhalt während des Jobs blockiertSiehe Abschnitt Sicherheit; dieselbe Eingabe erneut zu senden hilft nicht
Client-Timeout, Jobstatus unbekanntHTTP-Timeout kürzer als die Reasoning-ZeitGespeicherte Interaction-ID abfragen, bevor Sie neu einreichen
404 bei GETDie Interaction wurde gelöschtErgebnisse abrufen, bevor Sie löschen

Google empfiehlt für schwierige Prompts auf Carbon und Neon HTTP-Timeouts von mindestens 15 Minuten oder Hintergrundausführung. Abgebrochene und fehlgeschlagene Interactions werden für die bis zum Abbruch geleistete Arbeit abgerechnet. Ein Client, der in ein Timeout läuft und neu einreicht, kann dieselbe Aufgabe daher doppelt bezahlen. Speichern Sie die Interaction-ID, sobald Sie den Job anlegen.

Tool-Call-Fehler: Thought Signatures und fehlerhafte Aufrufe

Googles Seite zu API-Fehlern führt diese Generierungsfehlercodes auf: malformed_function_call, malformed_tool_call, unexpected_tool_call, too_many_tool_calls und missing_thought_signature.

MALFORMED_FUNCTION_CALL nach der Migration. Die Leitfäden zu Neon und Hydrogen warnen davor, das Modell per Systemanweisung dazu zu bringen, Tool-Calls als JSON in reinem Text auszugeben, wenn keine Tools deklariert sind, weil das MALFORMED_FUNCTION_CALL zurückgeben kann. Beheben Sie das, indem Sie Tools über die Function-Calling-Felder der API deklarieren oder für JSON strukturierte Ausgabe nutzen.

missing_thought_signature. Thought Signatures transportieren den Reasoning-Zustand des Modells zwischen Runden. Googles Regeln:

  • In der Interactions API mit store: true und previous_interaction_id kümmert sich der Server um die Signaturen. Sie müssen nichts tun.
  • Im zustandslosen Modus senden Sie jeden thought-Block exakt so zurück, wie Sie ihn erhalten haben, einschließlich der Blöcke des vorherigen Modells nach einem Modellwechsel und der Signaturen an Aufruf- und Ergebnisblöcken eingebauter Tools.
  • In clientseitig verwalteten generateContent-Verläufen geben Sie frühere Modellrunden und Signaturen unverändert zurück und kopieren keine Signatur auf parallele functionCall-Teile.

Wir haben Hydrogen über Ofox einen nativen generateContent-Verlauf mit einem functionCall-Teil ohne Signatur geschickt. Er wurde ohne Fehler angenommen, und das Modell antwortete auf Basis des Tool-Ergebnisses. Ein Durchlauf auf einer Route zeigt nicht, ob die Signaturprüfung lief oder der Verlauf anders behandelt wurde; lesen Sie das also nicht als Erlaubnis, Signaturen wegzulassen. Googles Migrations-Checklisten verlangen, Signaturen unverändert zurückzugeben. Für eine Reparatur Feld für Feld über REST, SDKs und Kompatibilitätsadapter nutzen Sie den Fix für missing thought_signature (Englisch). Bei Ofox trug die Chat-Completions-Antwort in unseren Tests die Signatur in message.reasoning_details (Typ reasoning.encrypted). Behalten Sie dieses Objekt, wenn Ihr Framework Assistant-Runden erneut sendet.

Sicherheits- und Recitation-Blockaden

Symptom. Googles Leitfaden zu Sicherheitseinstellungen sagt, eine blockierte Eingabe oder Antwort “fails with an HTTP 400 error” (schlägt mit einem HTTP-400-Fehler fehl), und der blockierte Inhalt wird nicht zurückgegeben. Das dokumentierte Beispiel:

{"error": {"code": "safety",
  "message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."}}

Eingabeblockaden nutzen die Codes jailbreak, prohibited_content oder blocklist, mit Meldungen, die mit Input blocked: beginnen. Googles Seite zu API-Fehlern führt weitere Codes für blockierte Generierung auf, darunter recitation, language, spii und content_blocked. Im Hintergrundmodus wechselt der Status der Interaction auf failed, und der Code erscheint in ihrer Liste errors. Beim Streaming kommt er als error-Event an.

Lösung. Behandeln Sie das als Inhaltsproblem, nicht als Ausfall, und wiederholen Sie nicht automatisch. Einstellbare Sicherheitsfilter stehen ab Gemini 2.5 standardmäßig auf Off, und manche Schadenskategorien werden unabhängig von den Einstellungen immer blockiert; lockerere Schwellenwerte heben also nicht jede Blockade auf. Formulieren Sie die legitime Anfrage um; versuchen Sie nicht, den Filter zu umgehen. BlockedReason.OTHER bedeutet, dass die Anfrage möglicherweise gegen die Nutzungsbedingungen verstößt oder nicht unterstützt wird. Bei RECITATION schlägt Google vor, Prompt und Kontext eigenständiger zu gestalten. Der ältere Tipp zur Temperatur gilt nicht für Gemini 4, das temperature ignoriert.

Prüfen. Protokollieren Sie den Code zusammen mit der Request-ID, damit Sie im Monitoring Inhaltsblockaden von 5xx-Ausfällen unterscheiden können.

Fehler durch Migration und Deprecation

Die meisten 400-Fehler direkt nach einem Upgrade stammen aus Konfigurationen, die unter Gemini 3.x funktionierten. Hier die dokumentierten Breaking Changes für Carbon, Neon und Hydrogen aus Googles drei Migrations-Checklisten:

Alte KonfigurationVerhalten in Gemini 4Lösung
temperature, top_p, top_kIgnoriert, mit Deprecation-Warnheadern (Troubleshooting); Werte außerhalb des Bereichs liefern 400 (Leitfäden zu Neon und Hydrogen); laut Google wird ein künftiges Release 400 liefernAlle drei entfernen
cached_content, caches.createExplizites Caching nicht unterstütztEntfernen; implizites Caching greift ab Prompts mit 4.096 Tokens
thinking_level: "minimal"Von Neon und Hydrogen abgelehntlow verwenden
max_output_tokens: 8192Thinking verbraucht den Großteil des LimitsAuf 32.768–65.536 erhöhen
candidate_count größer als 1In Gemini 3 und 4 nicht unterstütztEntfernen

Zu den Sampling-Parametern: Unsere Ofox-Anfragen an Hydrogen mit temperature: 5 wurden sowohl über Chat Completions als auch über die native Route ohne Fehler angenommen (HTTP 200). Die vollständigen Antwortheader, die wir mitgeschnitten haben, enthielten keinen Deprecation-Warnheader; die Antworten zeigen also nicht, ob der Wert Google überhaupt erreicht hat. Laut Googles Hydrogen-Leitfaden liefern Werte außerhalb des Bereichs 400. Entfernen Sie den Parameter, damit sich derselbe Code auf jeder Route gleich verhält.

Abgekündigte Modell-IDs. Googles Deprecation-Seite nennt Stand 19. November 2026 für kein Gemini-4-Modell ein Abschaltdatum. Überraschungen gibt es bei älteren IDs. gemini-3.7-flash und gemini-3.5-flash werden bereits automatisch auf neuere Flash-Modelle umgeleitet. Ab dem 1. Dezember 2026 werden alle API-Anfragen an gemini-2.5-pro auf gemini-3.8-flash umgeleitet und zu den Preisen von 3.8 Flash abgerechnet. Eine Umleitung ist kein Fehler, verändert aber Modellverhalten und Kosten, ohne dass ein Fehler Sie warnt. Fixieren und protokollieren Sie das Feld modelVersion (Ofox liefert es als model oder modelVersion), damit Sie eine stille Routenänderung bemerken. Wenn Sie von 3.8 Flash wechseln, finden Sie im Migrationsleitfaden von Gemini 3.8 Flash zu Hydrogen einen Testplan für vorher und nachher.

Welche Fehler wiederholt werden sollten

Mit Backoff wiederholenAnfrage korrigieren, nicht wiederholenAuf Kapazität oder Abrechnung warten
429 Rate / too many requests, 500, 503, 504, 408, Status failed (einmal)400 jeder Art, 401, 403, 404, Sicherheits- und Generierungsblockade-Codes429 quota_exceeded, 402 payment_required, ausgabenbasiertes RESOURCE_EXHAUSTED

Das deckt sich mit Googles Empfehlung, 400, 402 und 403 nicht zu wiederholen, und mit der Tabelle von Ofox, in der 400, 401, 402, 403 und 404 nicht wiederholbar und 429, 500, 502 und 503 wiederholbar sind. Einen Vergleich der Statuscodes verschiedener Anbieter bietet die Referenz zu LLM-API-Fehlercodes (Englisch).

Was wir getestet haben und was nicht

Getestet über Ofox am 19. November 2026, ein Durchlauf pro Fall (plus zwei Wiederholungen des Temperatur-Falls, um die vollständigen Header mitzuschneiden): falsche IDs, nicht gelistete Modelle, die ID ohne Präfix, drei Thinking-Level-Werte (minimal, xhigh und ein ungültiger) in fünf Anfragen, übergroße und winzige Ausgabelimits, eine Temperatur außerhalb des Bereichs, ein Tool-Verlauf ohne Signatur und ein ungültiger Key (401, Typ invalid_api_key, Meldung Invalid or expired API key). Die Prompts waren trivial (“Reply with the single word OK” und eine einzeilige Rechenfrage). Rohe Anfragen und Antworten sind gespeichert, der Key ist geschwärzt.

Nicht getestet: Carbon- oder Neon-Aufrufe am Google-Endpunkt, 403-Fehler der kostenlosen Stufe, echte 429, Sicherheitsblockaden, Hintergrundjobs und Kontextüberlauf. Diese Abschnitte stützen sich auf Googles Dokumentation, und Meldungen zitieren wir nur dort, wo Google oder Ofox sie abdrucken. Ein 200 in unseren Durchläufen bedeutet nur, dass die Anfrage nicht abgelehnt wurde. Das Verhalten des Gateways kann sich ohne Ankündigung ändern; prüfen Sie die Parameterfälle auf Ihrer eigenen Route erneut.

Wenn Sie noch bei der Einrichtung sind, beginnen Sie mit dem Setup-Leitfaden für die Hydrogen API, dem Setup-Leitfaden für die Carbon API oder dem Leitfaden zur Neon API und kommen Sie hierher zurück, wenn eine Anfrage fehlschlägt.

Weiterführende Dokumentation

Häufig gestellte Fragen

Warum ist meine Gemini-4-Anfrage erfolgreich, liefert aber keinen Text?
Thinking und sichtbare Ausgabe teilen sich max_output_tokens. Ist das Limit niedrig, kann das Modell das gesamte Budget für Thinking verbrauchen. In unserem Test über Ofox lieferte Hydrogen mit max_tokens 16 HTTP 200 mit leerem content und finish_reason "length". Erhöhen Sie das Limit (Google empfiehlt für Carbon mindestens 32.768 und für Neon und Hydrogen den Standardwert 65.536) oder senken Sie thinking_level.
Kann ich Gemini 4 Carbon oder Neon über Ofox aufrufen?
Stand 19. November 2026 nicht. In unserem Test gaben beide IDs auf Ofox 404 model_not_found zurück. Gemini 4 Hydrogen und Gemini 4 Argon sind gelistet. Für Carbon und Neon nutzen Sie die kostenpflichtige Stufe von Google.