Gemini 4 APIのエラーを切り分ける:Carbon・Neon・Hydrogenの原因と対処

Gemini 4 Carbon・Neon・HydrogenのAPIエラーを、ステータスコードと応答の形から診断します。モデルIDの誤り、無料枠の制限、429、思考レベル、空の応答、ツール呼び出し、安全性ブロックを扱います。

開いた分電盤の線画。2列に並んだスイッチのうち、オレンジ色の1つだけが落ちている。

Gemini 4のAPIエラーの多くは、次の5つに分類できます。モデルIDやルートの誤り、プロジェクトの利用枠(CarbonとNeonは有料枠のみ)、クォータ(429)、サポートされていないパラメータ(minimal、またはCarbonでの xhigh)、そして思考が max_output_tokens を使い切ったために、形式上は成功しても回答が入っていない応答です。 HTTPステータス、エラーの code、応答の形から、どれに当たるかを判断してください。新しいAPIキーで解決するのは、キーが漏えいした、またはブロックされたという限られたケースだけです。

この記事はGemini 4のCarbon、Neon、Hydrogenを対象にしています。Argonについては別記事のGemini 4 Argon APIエラーの対処があり、そちらのインシデント記録テンプレートや合成テストケースはここでは繰り返しません。以下のGoogle側の事実はGemini APIのドキュメントに基づき、2026年11月19日に確認しました(本文中のGoogleドキュメントへのリンクはすべて英語ページです)。Ofox側の結果は、同日にOfox経由で google/gemini-4-hydrogen と google/gemini-4-argon に送った21件の実リクエストによるもので、各ケース1回ずつ実行しました(総費用の見積もりは0.05ドル未満)。CarbonとNeonはOfoxでは利用できないため(2026年11月19日にカタログを確認)、CarbonとNeonの例はすべてGoogleのネイティブAPIを使っています。

この記事はOfoxが公開しています。ゲートウェイでの結果がGoogleのドキュメントと異なる場合は両方を示し、その違いをGoogle自身のエンドポイントのルールとしては扱いません。

まず症状から診断する

上から見て、最初に当てはまる行を使ってください。各行から、修正方法と確認手順を書いたセクションに移動できます。

見えている現象最も可能性の高い原因最初に確認することセクション
404 model_not_found入力ミス、勝手に付けたサフィックス、またはそのルートが提供していないモデルプロバイダーの最新モデル一覧からIDをコピーするモデルID
認証、無料枠、支払いに触れた 403 PERMISSION_DENIEDプロジェクトの利用枠または課金状態キーではなく、AI Studioのプロジェクト状態有料枠
402 payment_requiredプリペイドクレジットの枯渇課金残高。再試行しない有料枠
rate_limit_exceeded / too_many_requests を伴う 4291分あたりのバースト同時実行数とトークン速度429
quota_exceeded を伴う 4291日のクォータを使い切ったリセットを待つ。再試行しても効果なし429
thinking_level に触れた 400そのモデルでは無効なレベルモデル別のレベル表思考レベル
Gemini 3.xから移行した後の 400古いサンプリング、キャッシュ、ツール指示の設定移行チェックリスト移行
HTTP 200、テキストが空、MAX_TOKENS / length / incomplete思考が出力予算を使い切ったmax_output_tokens と thinking_level出力予算
ステータスが requires_continuationフォアグラウンドの1回分が上限に達したSDKのバージョンまたは継続ループ出力予算
バックグラウンドジョブが failed または止まったままサーバー側の失敗、24時間の制限、または store=falseインタラクションの状態と errors リストバックグラウンド
missing_thought_signature、malformed_function_callツール呼び出しの履歴が改変された、またはツールが宣言されていない履歴をどう再送しているかツール呼び出し
code が safety、prohibited_content の 400コンテンツフィルタープロンプトと安全性設定安全性

メッセージより先にエラーの形を見る

GoogleとOfoxのようなゲートウェイでは、エラーの形式が異なります。テキストに従って対処する前に、どちらが応答したのかを確認してください。

GoogleのInteractions APIは、機械で読み取れる code と message を持つ error オブジェクトを返します。GoogleのAPIエラーリファレンスの例は次のとおりです。

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

ストリーミングでは、同じオブジェクトが "event_type": "error" を持つSSEイベントとして届きます。ストリームはHTTP 200で始まった後に失敗することもあるため、ストリームを読むコードはerrorイベントを処理する必要があります。旧来の generateContent APIは古いGoogle RPC形式を使い、INVALID_ARGUMENT や RESOURCE_EXHAUSTED といったステータス名を返します。Googleのトラブルシューティングページに両方の命名が出てくるのはこのためです。

Ofoxゲートウェイは、テストで2種類の形を返しました。モデルIDがゲートウェイのカタログにない場合、ゲートウェイ自身のエラー本文が返ります(リクエストIDは短縮しています)。メッセージの形式は、Ofox GeminiガイドにあるモデルIDの綴り間違いの行と同じです。

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

リクエストがGoogle側に届き(Ofox Geminiガイドによると、OfoxはVertex AI経由でGeminiを提供しています)、そこで拒否された場合は、上流のテキストがゲートウェイの形式に包まれて返ってきます。

{"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"}}

メッセージに google.cloud.aiplatform の型名があれば、上流のモデルサービスがその値を拒否したということです。Model '<id>' not found というメッセージなら、ゲートウェイがモデルIDを認識できなかったということです。

Ofoxのエラー処理ガイドには、ステータスコードと、どれが再試行可能かが記載されています。そこにあるエラー本文の例は "code": "invalid_api_key" と "type": "authentication_error" で、表では404のtypeが not_found_error となっています。2026年11月19日に実際に受け取った本文は形が異なりました。401は "code": 401 と "type": "invalid_api_key"、404は "code": 404 と "type": "model_not_found" でした。これらのフィールドで処理を分岐させている場合は、code と type の両方を確認し、自分のルートで取得した実際のエラーでテストしてください。

404 model not found:IDかルートが間違っている

症状。Google:code が model_not_found の 404。Ofox:type が model_not_found で、メッセージが Model '<id>' not found の 404。

原因。Google APIでのGemini 4の4つのIDは、正確に gemini-4-carbon、gemini-4-neon、gemini-4-hydrogen、gemini-4-argon です(モデルページ)。どれにも -preview や -latest のサフィックスはありません。もう1つのよくある原因は、そもそもそのモデルを提供していないルートを使っていることです。

2026年11月19日にOfox経由で送ったリクエスト(各1回):

送ったモデル文字列エンドポイント結果
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(google/ プレフィックスなし)/v1/chat/completions200、応答の model フィールドは google/gemini-4-hydrogen

対処。Googleではプレフィックスを付けないIDを使います。Ofoxでは google/gemini-4-hydrogen または google/gemini-4-argon を使います。プレフィックスなしの形もテストでは解決され、Ofox Geminiガイドにもプレフィックスは省略可能と書かれています。CarbonやNeonを使うには、Googleの有料枠のプロジェクトを使ってください。綴りを変えても、ゲートウェイに掲載されていないモデルが現れることはありません。

確認。アプリが使っているのと同じエンドポイントとキーでモデル一覧を取得します。Googleでは GET https://generativelanguage.googleapis.com/v1beta/models、Ofoxでは GET https://api.ofox.ai/v1/models です。Googleによると、models.list が確認するのはキーが存在するかどうかだけです。一覧エンドポイントが200を返しても、そのプロジェクトで推論が有効だとは限らないため、小さな生成リクエストを1回送って確認してください。

無料枠のプロジェクトでCarbonとNeonが失敗する

症状。Hydrogenでは動くリクエストが、モデルをCarbonやNeonに変えると失敗します。よく見られるのは、403 PERMISSION_DENIED、AI Studioのプロジェクト状態が Free tier unavailable または Payment needed になっていること、あるいは一度も課金していないプロジェクトでのクォータエラーです。

原因。CarbonのガイドにはCarbonが “is not available on the Free tier”(無料枠では利用できない)と書かれています。NeonのガイドではNeonは “available on the paid tier only”(有料枠のみ)です。無料枠があるGemini 4モデルはHydrogenだけです(料金ページ)。無料枠のプロジェクトがCarbonやNeonを呼び出したときのモデル固有のエラー文字列をGoogleは公開していないため、文字列の完全一致で判定しないでください。ステータスで判定してから、プロジェクトを確認します。

Googleのトラブルシューティングガイドには、プロジェクト単位の403のバリエーションが載っています。

シグナル意味対処
FREE_TIER_VERIFICATION_REQUIRED を伴う 403、状態は Verification needed無料枠のプロジェクトに認証が必要モバイル端末で認証するか、課金を設定する
状態が Free tier unavailableそのプロジェクトは無料枠の対象外有効なCloud Billingアカウントを紐付ける
状態が Payment needed、または未払い残高に触れた 403課金アカウントが滞納している残高を支払えば、アクセスは自動的に戻る
キーが漏えいとして報告されたという 403Googleがキーをブロックした新しいキーを作成し、クライアントコードに含めない
402 payment_requiredプリペイドクレジットの枯渇クレジットを追加するか自動チャージを有効にする。再試行しない

つまずきやすい点が2つあります。対象かどうかはGoogle Cloudプロジェクト単位で判定されるため、同じプロジェクトの別のキーを使っても結果は変わりません。また、有料枠にアップグレードしても無料枠のクォータが解放されるわけではなく、有料の利用分は課金されます。無料枠で上限0と報告される 429 については、Gemini無料枠の上限0エラーの診断(英語)でクォータ指標の読み方を説明しています。画像モデルについての記事ですが、プロジェクトの確認方法は同じです。Hydrogenの無料枠に何が含まれるかは、Gemini 4の無料API枠ガイドを参照してください。

確認。AI Studioでキーを所有するプロジェクトを開き、利用枠を確認します。そのうえで、短いCarbonまたはNeonのリクエストを1回送ります。CarbonとArgonの料金は2026年12月1日に2倍になります(Carbonガイド)。具体的な数字は12月の料金改定の解説にあります。

429:一時的なバーストとクォータ切れを分ける

症状。HTTP 429。Interactions APIでは code が rate_limit_exceeded、too_many_requests、quota_exceeded のいずれかです。generateContent では RESOURCE_EXHAUSTED です。

原因。Googleのレート制限ページは3つの点を定めています。

  • 制限はAPIキー単位ではなくプロジェクト単位で適用されます。
  • 1日あたりのリクエストクォータは太平洋時間の午前0時にリセットされます。
  • 有料プロジェクトには、10分間のローリングウィンドウで計算される支出ベースの制限もあります。Tier 1は10ドル、Tier 2とTier 3は200ドルです。これを超えると、リクエスト速度が低くても 429 RESOURCE_EXHAUSTED が返ります。

Gemini 4では、この支出制限を見落としがちです。NeonとHydrogenはデフォルトで high の思考を使い、思考トークンは出力トークンとして課金されます。長く負荷の高いリクエストが少数あるだけで、RPMの制限に一度も触れずにTier 1の支出ウィンドウに達することがあります。

対処。code に合わせて対処します。

Codeやることやってはいけないこと
rate_limit_exceeded、too_many_requestsジッター付きの指数バックオフ、同時実行数を下げる並列ですぐに再試行する
quota_exceededリセットまでジョブを止めるか、クォータの追加を申請する1日のクォータに対して再試行の予算を使い果たす
支出ベースの RESOURCE_EXHAUSTED高コストの呼び出しを分散する、thinking_level や出力サイズを下げるRPM制限だと決めつける

GoogleのPython SDKは、429 と 5xx をすでに最大4回再試行します。間隔は約1秒から始まり、上限は60秒です(トラブルシューティング)。その外側に独自の再試行ループを重ねると、1回の失敗が十数件以上のリクエストに膨らむことがあります。再試行は1つの層だけに任せてください。一般的な429の再試行ガイドではヘッダーとバックオフのタイミングを、AI APIのエラー処理(英語)ではバックオフとサーキットブレーカーのコードを扱っています。

Ofoxの場合。ゲートウェイの429(エラー処理ガイドではtypeが rate_limit_error)は、Googleのプロジェクトクォータとは別の制限です。Ofoxのレート制限ドキュメントには、デフォルトが100 RPM(チーム内のすべてのキーの合計)と記載されています(2026年11月19日に再確認)。上限を引き上げたい場合は、そのページの説明に従ってOfoxにメールで依頼できます。テストでは429は発生しませんでした。

確認。429が起きるたびに正確な code をログに残してください。バックオフを入れても quota_exceeded が出続けるなら、問題はトラフィックの形ではなくクォータです。

思考レベルのエラー:minimalとxhigh

Gemini 4のモデルは、すべてが同じ思考レベルに対応しているわけではありません。Googleの思考ガイドの一覧は次のとおりです。

モデルデフォルト対応レベル
gemini-4-carbonmediumlow、medium、high
gemini-4-argonmediumlow、medium、high
gemini-4-neonhighlow、medium、high、xhigh
gemini-4-hydrogenhighlow、medium、high、xhigh

minimal はどのGemini 4モデルでもサポートされていません。NeonとHydrogenの移行チェックリストには、両モデルとも minimal をエラーで拒否すると書かれています。Googleの思考ガイドは gemini-3.8-flash でも minimal を非対応としているため、それを受け付けていた古いモデルからコピーした設定も同じように変更が必要です。GoogleはCarbonとArgonの上限を high としていますが、これらのモデルで xhigh を使った場合の正確なエラーメッセージは公開していません。

対処。古い設定を明示的に置き換えます。minimal は low に、CarbonとArgonでは xhigh を high にします。送信前に、自分のコードでモデルIDに対するレベルを検証してください。

ゲートウェイの実際の挙動。Ofoxでのテストからは、サーバー側でこれを止めてくれると期待すべきでない理由が分かります。

リクエスト(Ofox、2026-11-19、各1回)結果
Hydrogen、Chat Completions reasoning_effort: "minimal"200、エラーなし、推論トークン20
Hydrogen、ネイティブ thinkingLevel: "minimal"200、エラーなし、思考トークン22
Argon、Chat Completions reasoning_effort: "xhigh"200、エラーなし、推論トークン157
Argon、ネイティブ thinkingLevel: "xhigh"200、エラーなし、思考トークン131
Hydrogen、reasoning_effort: "banana"400 INVALID_ARGUMENT(上記のとおり)

Googleが無効としている値はエラーなしで受け付けられましたが、それで効果があったという意味ではありません。どのレベルが適用されたのかを示す情報は、応答のどこにもありません。ゲートウェイが値を捨てたのかもしれませんし、対応しているレベルに置き換えたのかもしれません。同じプロンプトで思考設定を指定しないHydrogenの実行は22〜82の思考トークンを使い、minimal の2回はそれぞれ20と22でした。したがって、1回ずつのトークン数からは何が起きたのか判断できません。Argonについては、比較用の基準となる実行を一度もしていません。でたらめな値は上流で拒否されました。これは、ある1日に1つのルートで1回ずつ観察した結果として扱ってください。この挙動に頼らないでください。ゲートウェイが受け付けたからといって minimal を送るコードは、Googleを直接呼び出したときに動かなくなる可能性があります。OfoxのGemini思考ガイドに thinkingLevel と reasoning_effort フィールドの説明があります。タスクに応じたレベルの選び方はGemini 4の思考レベルを参照してください。

回答が空、または途中で切れる:共有される1Mウィンドウ

症状。HTTP 200なのに、テキストが空か途中で切れています。ネイティブの generateContent では finishReason: "MAX_TOKENS"、Chat Completionsでは finish_reason: "length"、Interactionsのリソースではステータス incomplete になります。

原因。Gemini 4では、max_output_tokens が制限するのは思考と表示される出力の合計です。Googleの長文出力ガイドは、まさにこの症状を説明しています。ステータスが incomplete でテキストが空なら、“the model used all tokens on thinking.”(モデルがトークンをすべて思考に使った)という意味です。古いアプリから引き継いだ8,192のような上限があると、この状態がはるかに起きやすくなります。デフォルトが high のNeonとHydrogenでは特にそうです。

1行の計算問題を使い、Ofox経由のHydrogenでこれを再現しました。

ルート設定結果
Chat Completionsmax_tokens: 16200、content: ""、finish_reason: "length"、completionトークン16のうち13が推論
ネイティブ generateContentmaxOutputTokens: 16200、candidateに parts がない、finishReason: "MAX_TOKENS"、thoughtsTokenCount: 13

リクエストは失敗しておらず、課金もされています。回答だけがありません。アプリがHTTPステータスしか確認していなければ、空の応答がそのまま成功として扱われます。

対処。

  • 低い値をハードコードした上限を外します。GoogleはCarbonで32,768以上を推奨しています。NeonとHydrogenはデフォルトの65,536のままにするか、フィールド自体を省略します。
  • 使うトークンを減らしたいなら、thinking_level を下げます。Googleの長文出力ガイドによると、max_output_tokens を下げてもモデルの思考が簡潔になるわけではなく、応答が早く打ち切られるだけです。
  • 64Kトークンを超える出力が必要な場合は、background: true を設定し、max_output_tokens を65,536より大きく、最大で1,048,576から入力トークン数を引いた値まで設定します。

共有ウィンドウの制限。入力、思考、出力は1つの1,048,576トークンのウィンドウを共有します。Googleでは、入力と max_output_tokens の合計がウィンドウを超える場合、APIはリクエストを拒否せず、出力上限を残りの容量まで切り下げます(思考ガイド)。Ofoxで max_tokens: 2000000(Chat Completions)と maxOutputTokens: 2000000(ネイティブ)を送ったリクエストは、どちらもエラーなしで受け付けられ、通常どおり回答しました。ただし、実際にどの上限が適用されたかは応答からは分かりません。入力だけでウィンドウを超える場合はハードエラーになります。Ofox Geminiガイドには、400 INVALID_ARGUMENT とメッセージ The input token count exceeds the maximum number of tokens allowed 1048576. が記載されています。100万トークンのテスト入力はテスト予算を超えるため、このケースは再現していません。

1回あたりの上限。フォアグラウンドの1回分(hop)の上限は、NeonとHydrogenでは65,536トークンですが、CarbonとArgonの非ストリーミング呼び出しでは32,768です。予算が残っているのに1回分が上限に達すると、ステータスは requires_continuation になります。Python 2.34.0、JavaScript 2.32.0、Go 1.77.0、Java 1.80.0、.NET 1.28.0より古いSDKは、フォアグラウンドのインタラクションを自動では継続しません。SDKを更新するか、previous_interaction_id と continuation_token を付けて次の回を送ってください。

確認。応答をチェックするときは、HTTPステータスだけでなく、終了シグナル(status == "completed"、finishReason == "STOP"、または finish_reason == "stop")とテキストが空でないことを必ず確認してください。

バックグラウンド実行と長時間のインタラクション

時間のかかるCarbonやNeonのジョブは、バックグラウンド実行に回すべきです。Googleのバックグラウンド実行ガイドと長文出力ガイドには、次の失敗が記載されています。

症状原因対処
作成時に 400background: true と store: false の組み合わせバックグラウンドジョブでは store: true(デフォルト)のままにする
次のターンをつなげるときに 400前のインタラクションがまだ in_progresscompleted になってから、そのIDを previous_interaction_id として渡す
ステータス failed実行中のエラー(Googleの例:ツールの失敗、レート制限)、またはジョブが24時間を超えた1回だけ再試行し、再び失敗したらインタラクションIDをサポートに送る
errors に安全性のcodeがあるステータス failedジョブ中にコンテンツがブロックされた安全性のセクションを参照。同じ入力で再試行しても効果なし
クライアントのタイムアウトでジョブの状態が不明HTTPタイムアウトが推論時間より短い再送信する前に、保存したインタラクションIDをポーリングする
GETで 404インタラクションが削除された削除する前に結果を取得する

CarbonとNeonで難しいプロンプトを扱う場合、GoogleはHTTPタイムアウトを15分以上にするか、バックグラウンド実行を使うよう推奨しています。キャンセルされたインタラクションや失敗したインタラクションは、停止するまでに行われた処理分が課金されます。そのため、タイムアウトして再送信するクライアントは、同じタスクに2回支払うことになりかねません。ジョブを作成したら、すぐにインタラクションIDを保存してください。

ツール呼び出しのエラー:思考シグネチャと不正な呼び出し

GoogleのAPIエラーページには、生成時のエラーコードとして malformed_function_call、malformed_tool_call、unexpected_tool_call、too_many_tool_calls、missing_thought_signature が載っています。

移行後の MALFORMED_FUNCTION_CALL。NeonとHydrogenのガイドは、ツールを宣言していない状態で、システム指示を使ってモデルに生テキストのJSON形式でツール呼び出しを出力させないよう警告しています。そうすると MALFORMED_FUNCTION_CALL が返る可能性があるためです。APIのfunction callingフィールドでツールを宣言するか、JSONには構造化出力を使って解決してください。

missing_thought_signature。思考シグネチャは、ターン間でモデルの推論状態を引き継ぐものです。Googleのルールは次のとおりです。

  • Interactions APIで store: true と previous_interaction_id を使う場合、シグネチャはサーバーが処理します。何もする必要はありません。
  • ステートレスモードでは、すべての thought ブロックを受け取ったとおりに再送します。モデルを切り替えた後の前のモデルのブロックや、組み込みツールの呼び出しブロックと結果ブロックに付いたシグネチャも含みます。
  • クライアントが管理する generateContent の履歴では、以前のモデルのターンとシグネチャを変更せずに返し、1つのシグネチャを並列の functionCall パートにコピーしないでください。

Ofox経由で、シグネチャのない functionCall パートを含むネイティブ generateContent の履歴をHydrogenに送りました。リクエストはエラーなしで受け付けられ、ツールの結果に基づいて回答が返りました。1つのルートで1回実行しただけでは、シグネチャのチェックが行われたのか、履歴が別の形で処理されたのかは分かりません。シグネチャを省いてよいという意味に受け取らないでください。Googleの移行チェックリストは、シグネチャを変更せずに返すよう求めています。REST、SDK、互換アダプターにまたがるフィールド単位の修正は、missing thought_signatureの修正ガイドを参照してください。テストでは、OfoxのChat Completions応答はシグネチャを message.reasoning_details(typeは reasoning.encrypted)に入れていました。フレームワークがassistantのターンを再送する場合は、このオブジェクトを保持してください。

安全性ブロックと引用(recitation)ブロック

症状。Googleの安全性設定ガイドによると、ブロックされた入力や応答は “fails with an HTTP 400 error”(HTTP 400 エラーで失敗する)とされ、ブロックされた内容は返されません。ドキュメントの例は次のとおりです。

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

入力のブロックには jailbreak、prohibited_content、blocklist のcodeが使われ、メッセージは Input blocked: で始まります。GoogleのAPIエラーページには、recitation、language、spii、content_blocked など、生成がブロックされたことを示す他のcodeも載っています。バックグラウンドモードでは、インタラクションのステータスが failed になり、codeは errors リストに入ります。ストリーミングでは error イベントとして届きます。

対処。これらは障害ではなくコンテンツの問題として扱い、自動で再試行しないでください。Gemini 2.5以降では、調整可能な安全性フィルターはデフォルトでOffです。また、設定にかかわらず常にブロックされる有害カテゴリもあるため、しきい値を緩めてもすべてのブロックが解除されるわけではありません。正当なリクエストを書き直してください。フィルターを回避しようとしないでください。BlockedReason.OTHER は、リクエストが規約に違反しているか、サポートされていない可能性を示します。RECITATION については、プロンプトとコンテキストをより独自のものにするようGoogleは提案しています。temperatureに関する以前の助言は、temperature を無視するGemini 4には当てはまりません。

確認。codeをリクエストIDと一緒にログに残し、監視でコンテンツのブロックと5xxの障害を区別できるようにしてください。

移行と非推奨によるエラー

アップグレード直後に見られる 400 の多くは、Gemini 3.xでは動いていた設定が原因です。Googleの3つの移行チェックリストから、Carbon、Neon、Hydrogenで記録されている破壊的変更をまとめます。

古い設定Gemini 4での挙動対処
temperature、top_p、top_k無視され、非推奨の警告ヘッダーが付く(トラブルシューティング)。範囲外の値は 400 を返す(NeonとHydrogenのガイド)。Googleは将来のリリースで 400 を返すとしている3つとも削除する
cached_content、caches.create明示的キャッシュは非対応削除する。4,096トークン以上のプロンプトには暗黙的キャッシュが適用される
thinking_level: "minimal"NeonとHydrogenで拒否されるlow を使う
max_output_tokens: 8192思考が上限の大半を消費する32,768〜65,536に引き上げる
1より大きい candidate_countGemini 3と4では非対応削除する

サンプリングパラメータについては、Ofox経由でHydrogenに temperature: 5 を送ったところ、Chat Completionsとネイティブのどちらのルートでもエラーなしで受け付けられました(HTTP 200)。取得した応答ヘッダー全体に非推奨の警告ヘッダーはなかったため、その値がGoogleまで届いたのかどうかは応答からは分かりません。GoogleのHydrogenガイドは、範囲外の値は 400 を返すとしています。どのルートでも同じコードが同じように動くよう、このパラメータは削除してください。

非推奨のモデルID。Googleの非推奨ページには、2026年11月19日時点でGemini 4モデルの提供終了日は記載されていません。想定外のことが起きるのは古いIDのほうです。gemini-3.7-flash と gemini-3.5-flash は、すでに新しいFlashモデルに自動でルーティングされています。2026年12月1日からは、gemini-2.5-pro へのAPIリクエストはすべて gemini-3.8-flash にルーティングされ、3.8 Flashの料金で課金されます。ルーティングの変更はエラーではありませんが、警告となるエラーが一切出ないまま、モデルの挙動とコストが変わります。気づかないうちにルートが変わったことを把握できるよう、modelVersion フィールド(Ofoxでは model または modelVersion として返されます)を固定してログに残してください。3.8 Flashから移行する場合は、Gemini 3.8 FlashからHydrogenへの移行ガイドに移行前後のテスト計画があります。

どのエラーを再試行するか

バックオフして再試行リクエストを直し、再試行しない容量か課金の回復を待つ
429 のレート制限 / too many requests、500、503、504、408、ステータス failed(1回)あらゆる 400、401、403、404、安全性と生成ブロックのcode429 quota_exceeded、402 payment_required、支出ベースの RESOURCE_EXHAUSTED

これは、400、402、403 を再試行しないというGoogleの指針とも、400、401、402、403、404 を再試行不可、429、500、502、503 を再試行可能とするOfoxの表とも一致します。プロバイダー間でステータスコードを比較するには、LLM APIエラーコードのリファレンスを参照してください。

テストしたこと、していないこと

2026年11月19日にOfox経由で、各ケース1回ずつテストしました(temperatureのケースのみ、応答ヘッダー全体を取得するために2回追加で実行)。対象は、誤ったID、掲載されていないモデル、プレフィックスなしのID、5件のリクエストにわたる3種類の思考レベルの値(minimal、xhigh、無効な値)、非常に大きな出力上限と非常に小さな出力上限、範囲外のtemperature、シグネチャのないツール履歴、無効なキー(401、type invalid_api_key、メッセージ Invalid or expired API key)です。プロンプトはごく簡単なもの(“Reply with the single word OK” と1行の計算問題)です。生のリクエストと応答は、キーを伏せたうえで保存しています。

テストしていないもの:GoogleのエンドポイントでのCarbonやNeonの呼び出し、無料枠の403、実際の429、安全性ブロック、バックグラウンドジョブ、コンテキストのオーバーフロー。これらのセクションはGoogleのドキュメントに基づいており、メッセージを引用しているのはGoogleまたはOfoxが明記している場合だけです。テストでの200は、リクエストが拒否されなかったことしか意味しません。ゲートウェイの挙動は予告なく変わることがあるため、パラメータのケースは自分のルートで確認し直してください。

まだ接続の準備中であれば、Hydrogen APIのセットアップガイド、Carbon APIのセットアップガイド、またはNeon APIガイドから始め、リクエストが失敗したときにこの記事に戻ってきてください。

関連ドキュメント

よくある質問

Gemini 4のリクエストは成功したのに、テキストが返ってこないのはなぜですか?
思考と表示される出力は max_output_tokens を共有しています。上限が低いと、モデルが予算をすべて思考に使い切ることがあります。Ofox経由のテストでは、Hydrogenで max_tokens を16にするとHTTP 200が返り、content は空、finish_reason は "length" でした。上限を引き上げる(GoogleはCarbonで32,768以上、NeonとHydrogenではデフォルトの65,536を推奨)か、thinking_level を下げてください。
Gemini 4 CarbonやNeonはOfox経由で呼び出せますか?
2026年11月19日時点では呼び出せません。テストでは、どちらのIDもOfox上で 404 model_not_found を返しました。Ofoxに掲載されているのはGemini 4 HydrogenとGemini 4 Argonです。CarbonとNeonはGoogleの有料枠で利用してください。