Gemini APIが「つながりにくい」と感じるとき、原因は回線だけとは限りません。まず見るべきなのは、返ってきたHTTPステータスとエラー本文です。とくに、たまに成功してたまに失敗するなら、429の利用上限、503の一時的な混雑、クライアントやプロキシのタイムアウトを先に疑うと切り分けやすくなります。
元のメモには「実際にエラーが出ている」という状況はありますが、HTTPステータスやログ本文までは残っていません。そこで個別の原因を断定せず、次に同じエラーが出たときに原因を特定できる順番で整理します。
最初に結論:接続不良ではなく、エラーコードごとに見る
Googleの公式資料では、Gemini APIの失敗理由をHTTPステータスとJSONのerror.code、error.status、error.messageで確認できます。「接続が悪い」でまとめず、この3項目を残すのが第一歩です。
| 主なコード | よくある原因 | 最初にすること |
|---|---|---|
| 400 | リクエスト形式、パラメータ、APIバージョンが不正 | 送信内容とモデルが対応するAPIバージョンを確認 |
| 402 | Prepayクレジット不足 | 残高を確認。補充前の再試行はしない |
| 403 | APIキーや権限が不適切 | キーの設定先、対象プロジェクト、権限を確認 |
| 404 | モデルや参照ファイルなどが見つからない | モデルID、APIバージョン、参照先を確認 |
| 429 | RPM、TPM、RPD、支出ベースの上限超過 | 送信頻度と入力サイズを下げ、時間を空けて再試行 |
| 499 | 処理完了前に呼び出し元が接続を閉じた | クライアント、ワーカー、プロキシのタイムアウトを確認 |
| 500 | Google側の一時エラー、または長すぎる入力 | ステータスページ確認、入力縮小、時間を空けて再試行 |
| 503 | 一時的な過負荷や容量不足 | 指数バックオフで再試行し、障害情報も確認 |
| 504 | 期限内に処理が終わらない | 入力を小さくし、クライアントのタイムアウトも見直す |
「たまに失敗する」4つの典型パターン
1. リクエスト数ではなく、トークン量で429になっている
Gemini APIのレート制限には、1分あたりのリクエスト数(RPM)だけでなく、1分あたりの入力トークン数(TPM)や1日あたりのリクエスト数(RPD)があります。どれか1つでも超えると制限にかかります。
短いテストは通るのに実運用だけ失敗する場合、長い会話履歴や大きなファイルでTPMを使い切っている可能性があります。また、制限はAPIキー単位ではなくプロジェクト単位です。複数のサーバーやバッチが同じプロジェクトを使っているなら、各プロセスが単独で上限内でも合計で429になります。
2. 503を待たずに一斉再試行している
503はサービスの一時的な過負荷で返ることがあります。このとき即時リトライを繰り返すと、同じタイミングで再び混雑へぶつかります。複数ワーカーが同時に失敗した場合は、全ワーカーが同じ秒数で再試行する「再試行の集中」も起きます。
対策は指数バックオフにランダムな揺らぎ(jitter)を加えることです。たとえば1秒、2秒、4秒と待ち時間を伸ばし、そこに短い乱数を加えます。回数と合計待ち時間には上限を設けます。
3. Geminiではなく、手前のタイムアウトで切れている
アプリからGemini APIまでの間に、HTTPクライアント、ジョブワーカー、リバースプロキシなどがあると、それぞれにタイムアウトがあります。APIの処理が続いていても、手前の制限が先に来れば呼び出し元が接続を閉じます。Googleのエラー表では、499はこのような「呼び出し元によるキャンセル」の確認対象です。
見るべきなのはGemini SDKの設定だけではありません。外側のタイムアウトが内側より短くなっていないか、長い生成を同期HTTP処理のまま待っていないかも確認します。
4. Previewやlatestのモデル名を本番で使っている
Googleは、多くの本番アプリで特定のStableモデルを使うことを案内しています。PreviewやExperimentalはレート制限が厳しい場合があり、提供状況も変わりやすい区分です。latestは参照先のモデルが更新されるエイリアスなので、同じ文字列でも裏側が切り替わる可能性があります。
モデル変更の直後から不安定になったなら、モデルIDが現在も有効か、必要な機能がそのAPIバージョンで使えるかを公式のモデル一覧で確認します。
原因を特定する手順
手順1:失敗時の情報を1件にまとめる
次の項目を同じログ行、または同じトレースIDで追えるようにします。
- 発生日時と処理時間
- HTTPステータス
error.statusとerror.message- モデルIDとAPIバージョン
- 入力トークン数、または入力文字数の目安
- 同時実行数と再試行回数
- クライアント側でタイムアウトしたか
APIキー、個人情報、全文プロンプトはそのまま記録しません。必要なら内容を伏せたハッシュや文字数だけを残します。
手順2:最小のリクエストを1回だけ送る
同じAPIキーとモデルで、短いテキストだけのリクエストを1件送ります。これが通るなら、認証や基本的な接続は成立しています。実運用のリクエストだけ失敗する場合は、入力サイズ、対応していないパラメータ、同時実行、処理時間へ範囲を絞れます。
最小リクエストも403や404で失敗するなら、再試行より先にキー、権限、モデルID、APIバージョンを直します。
手順3:同じ時刻の件数と入力サイズを比べる
429なら、失敗直前の1分間に送った件数と入力トークン量を集計します。複数のコンテナやサーバーがある場合は、1台ずつではなくプロジェクト全体で合算します。503や500なら、同時刻の成功率とGoogle Cloud Service Healthも確認します。
手順4:タイムアウトの場所を特定する
毎回ほぼ同じ秒数で失敗するなら、固定のタイムアウト設定が疑わしいです。アプリ、SDK、ワーカー、プロキシの各上限を並べ、どこが最初に接続を切っているかを確認します。入力を半分にして処理時間が短くなるかを見るのも有効です。
再試行してよいエラー、直すまで再試行しないエラー
Googleのトラブルシューティングでは、429、408、5xx、ネットワークエラーなどの一時的な失敗に指数バックオフを使うよう案内しています。公式SDKには一時エラー向けの自動再試行が含まれるため、独自実装を重ねる前にSDK側の設定も確認してください。
一方、400、402、403は設定や入力、残高の問題です。内容を変えずに繰り返しても直りません。404も対象のモデルやリソースが誤っているなら、まず参照先を修正します。
再試行する場合も、上限回数、合計待ち時間、二重実行の扱いを決めます。ユーザー操作から同じ処理が再送される構成では、アプリ側の再試行とSDKの自動再試行が重なっていないかも要確認です。
本番で安定させるための設定
- プロジェクト全体のレート制御:複数ワーカーで共有できるキューやレートリミッターを使う
- 入力サイズの管理:会話履歴を無制限に足さず、不要な文脈を削る
- 同時実行数の上限:負荷が集中しても一斉送信しない
- 指数バックオフ+jitter:一時エラーだけを対象にし、無限再試行を避ける
- Stableモデルの固定:本番は特定のStableモデルを基本にし、変更は検証してから反映する
- 安全なログ:コード、ステータス、処理時間、モデル、入力規模を残し、秘密情報は残さない
次にエラーが出たら、ここだけ確認
- HTTPステータスと
error.statusを保存する - 短い最小リクエストが通るか試す
- 429ならプロジェクト全体のRPM・TPM・RPDを確認する
- 499や504ならタイムアウトの場所と入力サイズを確認する
- 500や503なら間隔を空けて再試行し、公式ステータスも見る
- 400、402、403、404は再試行より設定修正を優先する
「Gemini APIの接続が悪い」という症状だけでは原因は決まりません。ただ、エラーコード、入力規模、同時実行数、失敗までの秒数が揃えば、API側の一時障害なのか、利用上限なのか、自分のシステムのタイムアウトなのかをかなり早く分けられます。

