Gemini 4 API Errors: Fix Carbon, Neon and Hydrogen Failures
Diagnose Gemini 4 Carbon, Neon and Hydrogen API errors: wrong model IDs, paid-tier blocks, 429s, thinking levels, empty output, tool calls and safety blocks.
Most Gemini 4 API errors fall into five groups: wrong model ID or route, project tier (Carbon and Neon are paid-tier only), quota (429), unsupported parameters (minimal, or xhigh on Carbon), and responses that technically succeed but contain no answer because thinking used up max_output_tokens. Work out which group you are in from the HTTP status, the error code and the response shape. A new API key fixes only one narrow case, a leaked or blocked key.
This guide covers Gemini 4 Carbon, Neon and Hydrogen. Argon has a separate guide, the Gemini 4 Argon API errors walkthrough, and this article does not repeat its incident template or synthetic test cases. Google facts below come from the Gemini API documentation, checked on November 19, 2026. The Ofox results come from 21 real requests we sent that day to google/gemini-4-hydrogen and google/gemini-4-argon through Ofox, one run per case (estimated total cost under $0.05). Carbon and Neon are not available on Ofox (catalog checked November 19, 2026), so every Carbon and Neon example here uses Google’s native API.
Ofox publishes this article. Where a gateway result differs from Google’s documentation, both are shown, and the difference is not presented as a rule for Google’s own endpoint.
Diagnose by symptom first
Use the first row that matches. Each row links to the section with the fix and the verification step.
| What you see | Most likely cause | First check | Section |
|---|---|---|---|
404 model_not_found | Typo, invented suffix, or a model your route doesn’t serve | Copy the ID from the provider’s current model list | Model ID |
403 PERMISSION_DENIED naming verification, free tier or payment | Project tier or billing state | AI Studio project status, not the key | Paid tier |
402 payment_required | Prepay credits depleted | Billing balance; don’t retry | Paid tier |
429 with rate_limit_exceeded / too_many_requests | Per-minute burst | Concurrency and token rate | 429 |
429 with quota_exceeded | Daily quota used up | Wait for the reset; retries won’t help | 429 |
400 mentioning thinking_level | Level not valid for that model | Per-model level table | Thinking levels |
400 after migrating from Gemini 3.x | Old sampling, caching or tool-prompting config | Migration checklist | Migration |
HTTP 200, empty text, MAX_TOKENS / length / incomplete | Thinking consumed the output budget | max_output_tokens and thinking_level | Output budget |
Status requires_continuation | A foreground hop hit its per-request cap | SDK version or continuation loop | Output budget |
Background job failed or stuck | Server-side failure, 24-hour limit, or store=false | Interaction status and errors list | Background |
missing_thought_signature, malformed_function_call | Tool history altered, or tools not declared | How history is resent | Tool calls |
400 with code safety, prohibited_content | Content filter | The prompt and your safety settings | Safety |
Read the error shape before the message
Google and a gateway such as Ofox format errors differently. Check which one answered before acting on the text.
Google’s Interactions API returns an error object with a machine-readable code and a message, per Google’s API errors reference:
{
"error": {
"code": "invalid_request",
"message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. ..."
}
}
During streaming, the same object arrives as an SSE event with "event_type": "error". A stream can start with HTTP 200 and still fail later, so your stream reader must handle error events. The legacy generateContent API uses the older Google RPC style, with statuses such as INVALID_ARGUMENT and RESOURCE_EXHAUSTED, which is why both naming styles appear in Google’s troubleshooting pages.
The Ofox gateway produced two shapes in our tests. When the model ID wasn’t in the gateway’s catalog, the gateway answered with its own error body (request ID shortened). It has the same message format as the misspelled-ID row in the Ofox Gemini guide:
{"error": {"message": "Model 'google/gemini-4-carbon' not found",
"type": "model_not_found", "code": 404, "request_id": "e0925435-..."}}
When the request reached Google’s side (Ofox serves Gemini through Vertex AI, per the Ofox Gemini guide) and was rejected there, the upstream text came back inside the gateway envelope:
{"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"}}
A google.cloud.aiplatform type name in the message tells you the upstream model service rejected the value. A Model '<id>' not found message means the gateway didn’t recognize the model ID.
Ofox’s error-handling guide documents the status codes and which ones are retryable. Its example error body has "code": "invalid_api_key" and "type": "authentication_error", and its table lists the 404 type as not_found_error. The bodies we received on November 19, 2026 were shaped differently: the 401 had "code": 401 and "type": "invalid_api_key", and the 404s had "code": 404 and "type": "model_not_found". If your handler branches on these fields, check both code and type, and test it against an error captured from your own route.
404 model not found: the ID or the route is wrong
Symptom. Google: 404 with code model_not_found. Ofox: 404 with type model_not_found and the message Model '<id>' not found.
Cause. The four Gemini 4 IDs on Google’s API are exactly gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen and gemini-4-argon (models page). None has a -preview or -latest suffix. The other common cause is a route that does not serve the model at all.
Our Ofox requests on November 19, 2026 (one run each):
| Model string sent | Endpoint | Result |
|---|---|---|
google/gemini-4-hydrogen-preview | /v1/chat/completions | 404 model_not_found |
google/gemini-4-hydrogen-preview | /gemini/v1beta/models/...:generateContent | 404 model_not_found |
google/gemini-4-carbon | /v1/chat/completions | 404 model_not_found |
google/gemini-4-neon | /v1/chat/completions | 404 model_not_found |
gemini-4-hydrogen (no google/ prefix) | /v1/chat/completions | 200, response model field google/gemini-4-hydrogen |
Fix. On Google, use the bare ID. On Ofox, use google/gemini-4-hydrogen or google/gemini-4-argon. The bare form also resolved in our test, and the Ofox Gemini guide says the prefix is optional. For Carbon or Neon, use a Google paid-tier project. Changing the spelling won’t make an unlisted model appear on a gateway.
Verify. List models from the same endpoint and key your app uses: GET https://generativelanguage.googleapis.com/v1beta/models on Google, or GET https://api.ofox.ai/v1/models on Ofox. Google warns that models.list checks only that the key exists. A 200 from the list endpoint does not prove inference is enabled for the project, so confirm with one small generation call.
Carbon and Neon fail on a free-tier project
Symptom. A request that works with Hydrogen fails when you switch the model to Carbon or Neon. Common signs are a 403 PERMISSION_DENIED, an AI Studio project status of Free tier unavailable or Payment needed, or a quota error on a project that has never been billed.
Cause. Carbon’s guide states that Carbon “is not available on the Free tier”. Neon’s guide says Neon is “available on the paid tier only”. Hydrogen is the only Gemini 4 model with a free tier (pricing). Google does not publish a model-specific error string for a free-tier project calling Carbon or Neon, so don’t match on exact text. Match on the status and then check the project.
Google’s troubleshooting guide lists the project-level 403 variants:
| Signal | Meaning | Fix |
|---|---|---|
403 with FREE_TIER_VERIFICATION_REQUIRED, status Verification needed | Free-tier project must verify | Verify with a mobile device, or set up billing |
| Status Free tier unavailable | The project is not eligible for the free tier | Link an active Cloud Billing account |
Status Payment needed, or 403 citing an outstanding balance | Billing account in arrears | Settle the balance; access returns automatically |
403 saying the key was reported as leaked | Google blocked the key | Create a new key, and keep it out of client code |
402 payment_required | Prepay credits depleted | Add credits or enable auto-reload; don’t retry |
Two details catch people out. Eligibility is checked per Google Cloud project, so another key from the same project gives the same result. Upgrading to the paid tier also doesn’t unlock free-tier quota; paid usage is billed. For a free-tier 429 that reports a limit of 0, the Gemini free-tier limit-of-zero diagnosis walks through reading the quota metric. It was written about image models, but the project check is the same. The Gemini 4 free API tier guide covers what Hydrogen’s free tier includes.
Verify. In AI Studio, open the project that owns the key and confirm the tier. Then send one short Carbon or Neon request. Carbon and Argon prices double on December 1, 2026 (Carbon guide); the December price change breakdown has the numbers.
429: separate a burst from an exhausted quota
Symptom. HTTP 429. On the Interactions API the code is rate_limit_exceeded, too_many_requests or quota_exceeded. On generateContent it is RESOURCE_EXHAUSTED.
Cause. Google’s rate limits page sets three facts:
- Limits apply per project, not per API key.
- Requests-per-day quotas reset at midnight Pacific time.
- Paid projects also have a spend-based limit on a rolling 10-minute window: $10 at Tier 1 and $200 at Tiers 2 and 3. Exceeding it returns
429 RESOURCE_EXHAUSTEDeven if your request rate is low.
The spend limit is easy to miss on Gemini 4. Neon and Hydrogen default to high thinking, and thinking tokens are billed as output tokens. A small number of long, high-effort requests can reach a Tier 1 spend window without breaking any RPM limit.
Fix. Match the fix to the code:
| Code | Do | Don’t |
|---|---|---|
rate_limit_exceeded, too_many_requests | Exponential backoff with jitter; lower concurrency | Retry immediately in parallel |
quota_exceeded | Pause the job until the reset, or request more quota | Burn the retry budget on a daily quota |
Spend-based RESOURCE_EXHAUSTED | Spread out expensive calls; lower thinking_level or output size | Assume it means the RPM limit |
Google’s Python SDK already retries 429 and 5xx up to four times, starting at about 1 second with a 60-second cap (troubleshooting). If you wrap it in your own retry loop, one failure can turn into a dozen or more requests. Let one layer own retries. The general 429 retry guide covers headers and backoff timing, and AI API error handling includes backoff and circuit-breaker code.
On Ofox. A gateway 429 (type rate_limit_error in the error-handling guide) is a separate limit from Google’s project quota. The Ofox rate-limits doc lists a default of 100 RPM, counted across all keys in a team (rechecked November 19, 2026). You can email Ofox to ask for a higher limit, as described on that page. We did not trigger a 429 in our tests.
Verify. Log the exact code with every 429. If quota_exceeded keeps appearing after you add backoff, the problem is quota, not traffic shape.
Thinking-level errors: minimal and xhigh
Gemini 4 models don’t support the same thinking levels. Google’s thinking guide lists:
| Model | Default | Supported levels |
|---|---|---|
gemini-4-carbon | medium | low, medium, high |
gemini-4-argon | medium | low, medium, high |
gemini-4-neon | high | low, medium, high, xhigh |
gemini-4-hydrogen | high | low, medium, high, xhigh |
minimal isn’t supported on any Gemini 4 model. The Neon and Hydrogen migration checklists say both models reject minimal with an error. Google’s thinking guide also lists minimal as unsupported on gemini-3.8-flash, so a config copied from an older model that accepted it needs the same change. Google says Carbon and Argon cap at high, but it doesn’t publish the exact error message for xhigh on those models.
Fix. Map old settings explicitly: minimal becomes low, and xhigh becomes high on Carbon and Argon. Validate the level in your own code against the model ID before sending.
What the gateway did. Our Ofox tests show why you shouldn’t rely on the server to catch this:
| Request (Ofox, 2026-11-19, one run each) | Result |
|---|---|
Hydrogen, Chat Completions reasoning_effort: "minimal" | 200, no error; 20 reasoning tokens |
Hydrogen, native thinkingLevel: "minimal" | 200, no error; 22 thought tokens |
Argon, Chat Completions reasoning_effort: "xhigh" | 200, no error; 157 reasoning tokens |
Argon, native thinkingLevel: "xhigh" | 200, no error; 131 thought tokens |
Hydrogen, reasoning_effort: "banana" | 400 INVALID_ARGUMENT (shown above) |
The values Google documents as invalid were accepted without an error, but that doesn’t mean they worked. Nothing in the responses shows which level was applied. The gateway may have dropped the value or mapped it to a supported one. On the same prompt, Hydrogen runs with no thinking setting used between 22 and 82 thinking tokens, and the two minimal runs used 20 and 22, so single-run token counts can’t tell us what happened. We didn’t run an Argon baseline at all. A made-up value was rejected upstream. Treat this as a single observation of one route on one day. Don’t rely on it: code that sends minimal because the gateway accepted it may break when you call Google directly. The Ofox Gemini thinking guide documents the thinkingLevel and reasoning_effort fields. For choosing a level by task, see Gemini 4 thinking levels.
Empty or truncated answers: the shared 1M window
Symptom. HTTP 200, but the text is empty or cut off. Native generateContent shows finishReason: "MAX_TOKENS", Chat Completions shows finish_reason: "length", and an Interactions resource shows status incomplete.
Cause. In Gemini 4, max_output_tokens limits thinking plus visible output combined. Google’s long decode guide gives this exact symptom: status incomplete with empty text means “the model used all tokens on thinking.” A cap carried over from an older app, such as 8,192, makes this much more likely, especially on Neon and Hydrogen, which default to high.
We reproduced it on Hydrogen through Ofox with a one-line arithmetic question:
| Route | Setting | Result |
|---|---|---|
| Chat Completions | max_tokens: 16 | 200, content: "", finish_reason: "length", 13 of 16 completion tokens were reasoning |
Native generateContent | maxOutputTokens: 16 | 200, candidate with no parts, finishReason: "MAX_TOKENS", thoughtsTokenCount: 13 |
The request didn’t fail and it was billed. Only the answer is missing. If your app checks the HTTP status alone, it will show a blank success.
Fix.
- Remove low hardcoded caps. Google recommends at least 32,768 for Carbon. For Neon and Hydrogen, keep the 65,536 default or omit the field.
- To spend fewer tokens, lower
thinking_level. Google’s long decode guide says loweringmax_output_tokensdoesn’t make the model think more concisely; it only cuts the response off sooner. - For output beyond 64K tokens, set
background: trueandmax_output_tokensabove 65,536, up to 1,048,576 minus your input tokens.
Shared-window limits. Input, thinking and output share one 1,048,576-token window. On Google, if input plus max_output_tokens exceeds the window, the API caps the output limit to the remaining space instead of rejecting the request (thinking guide). Our Ofox requests with max_tokens: 2000000 (Chat Completions) and maxOutputTokens: 2000000 (native) were both accepted without error and answered normally; the response doesn’t show what cap was actually applied. Input that alone exceeds the window is a hard error. The Ofox Gemini guide lists 400 INVALID_ARGUMENT with the message The input token count exceeds the maximum number of tokens allowed 1048576. We didn’t reproduce that one, because a million-token test input would have exceeded our test budget.
Per-hop caps. A single foreground hop is capped at 65,536 tokens on Neon and Hydrogen, but at 32,768 for non-streaming calls on Carbon and Argon. When a hop reaches its cap with budget left, the status is requires_continuation. SDKs older than Python 2.34.0, JavaScript 2.32.0, Go 1.77.0, Java 1.80.0 and .NET 1.28.0 don’t continue foreground interactions automatically. Upgrade, or send the next hop with previous_interaction_id and continuation_token.
Verify. Every response check should test the finish signal (status == "completed", finishReason == "STOP" or finish_reason == "stop") and that the text is non-empty, not just the HTTP status.
Background and long-running interactions
Long Carbon and Neon jobs belong in background execution. Google’s background execution guide and long decode guide document these failures:
| Symptom | Cause | Fix |
|---|---|---|
400 on create | background: true with store: false | Keep store: true (the default) for background jobs |
400 when chaining a follow-up turn | The previous interaction is still in_progress | Wait for completed before passing its ID as previous_interaction_id |
Status failed | An error during execution (Google’s examples: a tool failure, rate limits), or the job ran past 24 hours | Retry once; if it fails again, send the interaction ID to support |
Status failed with a safety code in errors | Content blocked during the job | See the safety section; retrying the same input won’t help |
| Client timeout, job state unknown | HTTP timeout shorter than the reasoning time | Poll the saved interaction ID before resubmitting |
404 on GET | The interaction was deleted | Retrieve results before deleting |
Google recommends HTTP timeouts of at least 15 minutes for hard prompts on Carbon and Neon, or background execution. Cancelled and failed interactions are billed for the work done before they stopped. A client that times out and resubmits can therefore pay twice for the same task. Save the interaction ID as soon as you create the job.
Tool-call errors: thought signatures and malformed calls
Google’s API errors page lists these generation error codes: malformed_function_call, malformed_tool_call, unexpected_tool_call, too_many_tool_calls and missing_thought_signature.
MALFORMED_FUNCTION_CALL after migration. The Neon and Hydrogen guides warn against prompting the model through system instructions to emit raw-text JSON tool calls when no tools are declared, because that can return MALFORMED_FUNCTION_CALL. Fix it by declaring tools through the API’s function-calling fields, or by using structured output for JSON.
missing_thought_signature. Thought signatures carry the model’s reasoning state between turns. Google’s rules:
- In the Interactions API with
store: trueandprevious_interaction_id, the server handles signatures. You don’t need to do anything. - In stateless mode, resend every
thoughtblock exactly as received, including the previous model’s blocks after a model switch, and the signatures on built-in tool call and result blocks. - In client-managed
generateContenthistories, return prior model turns and signatures unchanged, and don’t copy one signature onto parallelfunctionCallparts.
We sent Hydrogen a native generateContent history with a functionCall part that had no signature, through Ofox. It was accepted without an error and answered from the tool result. One run on one route doesn’t show whether the signature check ran or the history was handled differently, so don’t read it as permission to drop signatures. Google’s migration checklists tell you to return signatures unchanged. For a field-by-field repair across REST, SDKs and compatibility adapters, use the missing thought_signature fix. On Ofox, the Chat Completions response carries the signature in message.reasoning_details (type reasoning.encrypted) in our tests. Keep that object if your framework resends assistant turns.
Safety and recitation blocks
Symptom. Google’s safety settings guide says a blocked input or response “fails with an HTTP 400 error” and the blocked content isn’t returned. The documented example:
{"error": {"code": "safety",
"message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."}}
Input blocks use the codes jailbreak, prohibited_content or blocklist, with messages starting Input blocked:. Google’s API errors page lists other generation-blocked codes, including recitation, language, spii and content_blocked. In background mode the interaction’s status becomes failed and the code appears in its errors list. In streaming it arrives as an error event.
Fix. Treat these as content problems, not outages, and don’t retry automatically. Adjustable safety filters default to Off on Gemini 2.5 and later, and some harm types are always blocked regardless of settings, so loosening thresholds won’t clear every block. Rewrite the legitimate request; don’t try to bypass the filter. BlockedReason.OTHER means the request may violate the terms or be unsupported. For RECITATION, Google suggests making the prompt and context more unique. Its older temperature tip doesn’t apply to Gemini 4, which ignores temperature.
Verify. Log the code with the request ID so you can tell content blocks apart from 5xx failures in monitoring.
Migration and deprecation errors
Most 400 errors seen right after an upgrade come from configuration that worked on Gemini 3.x. Here are the documented breaking changes for Carbon, Neon and Hydrogen, from Google’s three migration checklists:
| Old config | Gemini 4 behavior | Fix |
|---|---|---|
temperature, top_p, top_k | Ignored, with deprecation warning headers (troubleshooting); out-of-range values return 400 (Neon and Hydrogen guides); Google says a future release will return 400 | Remove all three |
cached_content, caches.create | Explicit caching not supported | Remove; implicit caching applies at 4,096+ token prompts |
thinking_level: "minimal" | Rejected on Neon and Hydrogen | Use low |
max_output_tokens: 8192 | Thinking consumes most of the cap | Raise to 32,768–65,536 |
candidate_count above 1 | Unsupported on Gemini 3 and 4 | Remove |
On sampling parameters, our Ofox requests to Hydrogen with temperature: 5 were accepted without error (HTTP 200) through both Chat Completions and the native route. The full response headers we captured had no deprecation warning header, so the responses don’t show whether the value reached Google at all. Google’s Hydrogen guide says out-of-range values return 400. Remove the parameter so the same code behaves the same on every route.
Deprecated model IDs. Google’s deprecations page lists no shutdown date for any Gemini 4 model as of November 19, 2026. Older IDs are where surprises happen. gemini-3.7-flash and gemini-3.5-flash already route automatically to newer Flash models. From December 1, 2026, all gemini-2.5-pro API requests route to gemini-3.8-flash and are billed at 3.8 Flash rates. Rerouting isn’t an error, but it changes model behavior and cost without an error to warn you. Pin and log the modelVersion field (Ofox returns it as model or modelVersion) so you can see a silent route change. If you’re moving off 3.8 Flash, the Gemini 3.8 Flash to Hydrogen migration guide has a before-and-after test plan.
Which errors to retry
| Retry with backoff | Fix the request, don’t retry | Wait for capacity or billing |
|---|---|---|
429 rate / too many requests, 500, 503, 504, 408, status failed (once) | 400 of any kind, 401, 403, 404, safety and generation-blocked codes | 429 quota_exceeded, 402 payment_required, spend-based RESOURCE_EXHAUSTED |
This matches Google’s guidance not to retry 400, 402 or 403, and Ofox’s table, where 400, 401, 402, 403 and 404 are non-retryable and 429, 500, 502 and 503 are retryable. For a status-code comparison across providers, see the LLM API error codes reference.
What we tested and what we didn’t
Tested through Ofox on November 19, 2026, one run per case (plus two repeat runs of the temperature case to capture full headers): wrong IDs, unlisted models, the bare ID, three thinking-level values (minimal, xhigh and an invalid one) across five requests, oversized and tiny output caps, an out-of-range temperature, a tool history without a signature, and an invalid key (401, type invalid_api_key, message Invalid or expired API key). The prompts were trivial (“Reply with the single word OK” and a one-line arithmetic question). Raw requests and responses are saved with the key redacted.
Not tested: any Carbon or Neon call on Google’s endpoint, free-tier 403s, real 429s, safety blocks, background jobs, and context overflow. Those sections rely on Google’s documentation, and we quote messages only where Google or Ofox prints them. A 200 in our runs means only that the request wasn’t rejected. Gateway behavior can change without notice, so recheck the parameter cases on your own route.
If you’re still setting up, start with the Hydrogen API setup guide, the Carbon API setup guide or the Neon API guide, then come back here when a request fails.
Related Docs
- Ofox error handling and retries
- Ofox rate limits
- Ofox Gemini family guide and common errors
- Ofox Gemini native API
- Gemini 4 Hydrogen on Ofox (current price and supported protocols)
Frequently Asked Questions
- Why does my Gemini 4 request succeed but return no text?
- Thinking and visible output share max_output_tokens. With a low cap the model can spend the whole budget on thinking. In our Ofox test, max_tokens 16 on Hydrogen returned HTTP 200 with empty content and finish_reason "length". Raise the cap (Google recommends at least 32,768 on Carbon and the 65,536 default on Neon and Hydrogen) or lower thinking_level.
- Can I call Gemini 4 Carbon or Neon through Ofox?
- Not as of November 19, 2026. Both IDs returned 404 model_not_found on Ofox in our test. Gemini 4 Hydrogen and Gemini 4 Argon are listed. Use Google's paid tier for Carbon and Neon.


