Gemini 4 Argon APIのエラー対処：403・404・429と空の応答を切り分ける

APIキーを作り直す前に、接続先と生のレスポンスを確認してください。Gemini 4 Argonへのリクエストが失敗する原因には、クライアントの送信形式の誤り、プロジェクトの権限不足、指定リソースの不在、割り当て上限への到達などがあります。応答が空に見えても、アプリが誤ったフィールドを読んでいるだけの場合や、処理がまだ終わっていない場合があります。

本記事はGoogleのGemini Developer APIを対象とし、Interactions APIの例を2026年10月23日時点の公式ドキュメントと照合しています。Vertex AI、OpenAI互換プロキシ、Ofox、Antigravityからの利用可否を確認したものではありません。例はドキュメントに基づいており、後半の診断演習もローカルでの合成テストです。Argonの実API呼び出しに成功したという報告ではありません。

アプリのモデル選択欄に表示されない場合は、Gemini 4 Argonのアクセスガイドから確認してください。APIリクエストが実際に失敗した場合は、以下の順に調べます。

アプリの警告とAPIエラーを区別する

「currently available to Ultra plan subscribers」のような表示は、アカウントや製品の利用条件を確認する手がかりです。これだけでAPIがHTTP 403を返したとは判断できません。Geminiアプリ、AntigravityアプリやCLI、AI Studio、自社バックエンド、サードパーティー製クライアントのどこに表示されたかを記録してください。アプリの契約とAPIプロジェクトの設定は、別々に確認する必要があります。

APIの失敗では、設定を変える前に次の6項目を集めます。

1. リクエスト先のホスト名とパス。キーやクエリ文字列内の認証情報は除きます。
2. 正確なモデルIDとSDK／クライアントのバージョン。
3. HTTPステータス、レスポンスのContent-Type、機密情報を伏せたエラー本文。
4. UTCの発生日時、経過時間、すでに実行した試行回数。
5. 選択したプロジェクトと、ストリーミング／バックグラウンド実行の有無。
6. 返された場合はinteraction IDやrequest ID。共有は適切なサポート窓口に限定します。

社内ゲートウェイが返した403のHTMLページと、JSON形式のpermission_deniedでは、調べる場所が違います。同様に、ログにstatus=500と書かれているだけでは、GoogleがHTTP 500を返した証拠になりません。実際の上流レスポンスを確認してください。HTTPレスポンス自体が届いていない場合は、APIエラーコードを当てはめる前にDNS、TLS、接続状態、クライアントのタイムアウトを調べます。

最小リクエストで失敗箇所を絞る

GoogleのArgonクイックスタートは、InteractionsエンドポイントとモデルIDgemini-4-argonを使用しています。診断時はファイルのアップロード、ツール、以前の会話状態、追加の生成設定を外します。プロジェクトは、失敗したアプリと同じものを使ってください。

以下は利用権限のある自分のアカウントで実行する、課金対象のリクエストテンプレートです。執筆時にArgonへ実行したコマンドではありません。curlと、環境変数GEMINI_API_KEYに設定済みのAPIキーが必要です。キーを問い合わせに貼り付けたり、リポジトリへコミットしたりしないでください。クライアント側の90秒制限は診断用の設定であり、Googleが保証する応答時間ではありません。この制限に達しても、サーバー側の処理結果は不明のままです。

umask 077
curl --silent --show-error \
  --connect-timeout 10 --max-time 90 \
  --request POST \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  --header "x-goog-api-key: ${GEMINI_API_KEY:?Set GEMINI_API_KEY locally}" \
  --header 'Content-Type: application/json' \
  --data '{"model":"gemini-4-argon","input":"Reply with the word OK."}' \
  --dump-header argon-headers.txt \
  --output argon-response.json \
  --write-out 'HTTP %{http_code}; elapsed %{time_total}s\n'

ここでは意図的に自動再試行を設定していません。まず1回分のレスポンスを保存し、分類します。curlの終了コードが0でも、転送が成功したという意味にとどまります。モデル呼び出しの成功を判断する前に、HTTPステータスと本文を確認してください。

最小リクエストは成功するのにアプリが失敗する場合は、会話状態、ファイル、ツール、独自の生成設定の順に、機能を1つずつ戻します。追加した機能と結果のステータスを小さな表に記録してください。最初に失敗した追加項目が調査範囲を絞る手がかりです。キー、モデル、ペイロード、SDKを同時に変えると、この比較ができなくなります。

両方とも失敗した場合は、そのエラー本文を使って次の分岐を判断します。別モデルでの成功は、その条件下でそのモデルが動いたことだけを示します。Argonへの権限や機能の互換性を証明するものではありません。

エラーごとに次の確認項目を選ぶ

以下のコードはInteractions APIのエラーリファレンスに基づきます。他のプロトコルではフィールド名が異なる場合があります。変換処理なしでOpenAIのchoices用パーサーや従来のcandidates用パーサーを使わないでください。

これは調査の分岐であり、特定の変更ですべてのエラーが直るという保証ではありません。たとえばプロキシが上流のエラーを置き換えている場合、画面上の404だけではGoogleがモデルIDを拒否したかどうかは分かりません。

古いGeminiクライアントからの移行後に400・404が出る場合

ホスト、APIバージョン、エンドポイント、ペイロードのスキーマ、レスポンスの解析方法を一組として書き出し、プロバイダーのドキュメントと照合してください。古いワークフローのモデル名だけを書き換えても、移行が完了したとは限りません。

GoogleのInteractions APIでは、上記の最小例のようにmodelとinputを使います。OpenAI互換のmessages形式の本文を、そのまま送らないでください。Googleは従来のgenerateContent APIも引き続きサポートしていますが、リクエストとレスポンスの形式は異なります。Interactionsの概要と移行案内で違いを確認できます。記事が新しいエンドポイントを使っているという理由だけで、正常に動いている既存の実装を書き直す必要はありません。

Argonのモデル仕様では、出力はテキストです。画像や音声を理解できることと、画像や音声を生成できることは別です。また、明示的キャッシュではなく暗黙的キャッシュに対応し、Live APIには対応していません。失敗するリクエストがこれらの未対応機能を必要とする場合は、その機能への対応が明記されたモデルやインターフェースを選びます。モデル名を変えるだけで機能を追加することはできません。

移行エラーを切り分ける際は、古いサンプリング設定を外してください。Googleのトラブルシューティングによると、Gemini 4は独自のtemperature、top_p、top_kを非推奨警告付きで無視し、今後のリリースでは拒否する予定です。現時点で必ず400になると断定せず、temperatureを上げればArgonの出力が直るとも考えないでください。

復旧の確認：最小リクエストが成功し、仕様に基づく修正を1つ加えたことで、最初に失敗していた機能も動くことを確認します。機密情報を除いた修正前後のペイロードを保存してください。最小リクエストがまだ404を返すなら、機能を追加せず、先に接続経路・モデル・リソースの不一致を解消します。

429：瞬間的な集中と割り当ての使い切りを区別する

Googleのレート制限はキー単位ではなく、プロジェクト単位です。同じプロジェクトで2本目のキーを作っても、別の割り当て枠にはなりません。AI Studioで、実際に使っているプロジェクトとモデルの有効な制限を確認してください。1分あたりのリクエスト数、1分あたりの入力トークン数、1日あたりのリクエスト数、適用される支出ベースの制限が対象です。

エラー詳細と利用履歴を合わせて判断します。1日の利用量が少なくても、一度にバッチを流せば短い時間枠の上限を超えることがあります。一方、1日の枠を使い切った場合、数秒後の再試行では解決しません。1日あたりのリクエスト上限は太平洋時間の午前0時にリセットされますが、すべての429がこの時刻に解消するわけではありません。

短時間の集中には、まず同時実行数を下げて処理をキューに入れます。長いプロンプトが原因なら、リクエスト数を減らすだけではトークン量の負荷を十分に下げられない場合があります。割り当てを使い切った場合は、繰り返し送信せず、該当するリセット時刻か承認済みの容量変更までジョブを停止します。

復旧方針には次の3点を含めます。

• 再試行を担当するコンポーネントを1つにする。SDKの動作を調べてから、外側に別の再試行ループを設けるか判断します。
• 一時的な失敗には、ジッターを加えた段階的な待機、試行回数の上限、経過時間の上限を設ける。再試行までの待機時間が指定されていれば従います。
• 継続するアクセス権、ペイロード、支払いの問題では停止し、役に立つメッセージを表示する。割り当て不足は一時障害向けの試行枠を消費せず、容量の回復を待ちます。

小規模な対話処理なら「合計3回まで、全体で2分以内」という方針も考えられます。これはアプリ側の設定例であり、Googleの割り当て上限でも、あらゆる処理に対する推奨値でもありません。バッチ処理には独自の期限と支出上限が必要です。Googleの再試行ガイドも上限のあるバックオフを案内していますが、再試行が無料になるわけでも、完了が保証されるわけでもありません。

HTTP 200なのに回答がない：完了状態と出力を確認する

通信の成功とタスクの成功は分けて判定します。ストリーミングではイベントを最後まで受信し、エラーイベントも処理してください。最初のHTTPステータスが成功でも、ストリームの完了は保証されません。バックグラウンド実行ではinteraction IDを保存し、ポーリングのたびに同じジョブを新規作成するのではなく、そのinteractionを取得します。

Interactionsリソースには、ツール呼び出しやモデル出力を含む実行ステップが記録されます。SDKのクイックスタートでは、ドキュメントにある便利なフィールドoutput_textを使います。生のJSONを解析する場合は、使用するエンドポイントとバージョンのスキーマに従ってください。配列の先頭要素が最終回答だと決めつけず、該当するモデル出力をすべて確認します。

表示されるテキストが空なら、次の順に確認します。

1. まだ実行中か。キュー待ちや実行中のinteractionは、完了した空の回答ではありません。IDを保持し、ジョブの期限内で状態を確認します。
2. ツールの実行待ちか。正しい関数呼び出しはアプリが処理すべき作業であり、利用者向けの文章とは限りません。引数を検証して、必要なツール処理を完了します。
3. ブロックまたは失敗しているか。返された理由を保存します。安全上の制限なら、正当なタスクの内容を見直すか、制限を説明します。サービス障害と決めつけたり、回避を試みたりしないでください。
4. トークン予算や解析の問題か。使用量、完了情報、生のレスポンスを画面表示と照合します。Argonの出力予算は思考と可視出力を含むため、無条件に小さな上限を設定すると推論タスクに支障が出ることがあります。上限を上げると想定費用も変わるため、先に状況を確認します。

GoogleのArgonガイドは、長い出力生成に対するバックグラウンド実行を説明しています。短い「OK」の診断リクエストに、長時間処理用の設定をそのまま持ち込まないでください。実際の作業を送信した後にクライアントがタイムアウトしても、サーバーでは処理が続いている可能性があります。可能であれば既存のinteractionを取得し、代替ジョブを始める前に重複のリスクを判断します。

復旧の確認：アプリが「処理待ち」「ツール実行」「テキスト出力完了」「失敗／ブロック」を区別できることを確認します。4種類とも空の成功メッセージとして表示してはいけません。

追加のAPIリクエストを送る前にローカルで処理を試す

以下の合成テストは、Googleの現在の稼働状況を再現するものではなく、アプリの判断を検証するためのものです。ネットワーク呼び出しを無効にし、UIやエラーハンドラーへ次のケースを入力します。

これらはテストシナリオであり、APIレスポンスの完全なフィクスチャではありません。SDK／APIのバージョンに合ったフィクスチャを作成してください。ログにキーや非公開のプロンプト内容が含まれていないこと、1回の利用者操作で再試行とフォールバックの両方が誤って起動しないことも確認します。

モデルを切り替える条件とサポートに送る情報

期限のあるタスクで代替モデルを使う場合は、入力形式、ツール、出力スキーマ、コンテキスト長に対応していることを先に確認します。小さなタスク別サンプルで受け入れ基準を満たすか検証し、モデルを変更したことを明示してください。同じメッセージを2回送信するような重複した副作用も防ぎます。非公開ファイルを別のプロバイダーへ送る前には、必要なデータ取り扱い条件を確認してください。

5xxが続く場合は、Google AI Studioのサービス状況を確認します。1件の利用者報告や自分のリクエスト1回の失敗だけでは、全体的な障害とは判断できません。最小リクエストでも失敗が続く場合は、機密情報を伏せた記録をプロバイダーに送ります。

UTCの発生日時とタイムゾーン：
プロバイダー／ホスト／エンドポイント／APIバージョン：
モデルID／SDKバージョン：
プロジェクト参照情報（非公開のサポート窓口のみ）：
HTTPステータス／エラーコード／機密情報を除いたメッセージ：
ストリーミングまたはバックグラウンド実行の有無：
interaction ID（返された場合）：
経過時間／合計試行回数：
最小リクエストの結果：
戻した機能のうち最初に失敗したもの：
期待した結果／実際の結果：

出力予算を増やしたり、診断リクエストを繰り返したりする前に、Argon APIの料金を確認してください。モデル選びにはArgonの比較記事も参考になります。本記事はOfoxが公開していますが、上記のGoogle直接接続の例は、Ofox経由でArgonを利用できる証拠ではありません。ワークフローを移す前に、プロバイダーの最新モデル一覧と対応プロトコルを確認してください。