Gemini API のよくあるエラー切り分け：401、404、429、地域制限（2026）

Gemini API のエラーは種類が多いように見えますが、実際に切り分けると大半は 4 つに分類できます。身元が違う、アドレスが違う、クォータが足りない、ネットワークが届かない。本当にモデル自体が原因の問題はむしろ少数です。

本記事ではエラーコードごとに分類し、最小リクエストから始める切り分け順序を示します。問題が起きたら、まず完全なエラー JSON を保存し、その順序に従って確認してください。キー、アドレス、モデルを同時に変更しないでください。

注記：Google、Gemini はその権利者の商標です。本記事は 2026 年 10 月時点の一般的なインターフェース形態を例にしており、API バージョン、クォータ、地域ポリシーは公式ドキュメントとサイト内のモデル価格を基準とします。

一、まずエラー本文の読み方を覚える

Google API のエラーは通常 JSON で返り、重要なフィールドは 3 つです。

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code は HTTP ステータスコード、status は機械可読なエラー種別、message には具体的な理由が含まれることが多く、details にはクォータ ID や推奨再試行時刻が入る場合があります。切り分けでは 3 つすべてを見ます。「429」だけを見ると、「毎分のレート制限なのか、日次クォータの使い切りなのか」を見落とします。

ステータスコード	よくある status	おおよその方向性
401	UNAUTHENTICATED	キーの欠落、無効、配置ミス
403	PERMISSION_DENIED	プロジェクト未開通、権限または地域の制限
404	NOT_FOUND	モデル名、API パス、バージョンの誤り
429	RESOURCE_EXHAUSTED	速度、同時実行、クォータの超過
400	INVALID_ARGUMENT / FAILED_PRECONDITION	パラメータ誤り、地域非対応、前提条件の不足
500/503	INTERNAL / UNAVAILABLE	上流の一時障害。通常はバックオフして再試行可能

二、401：キーが無効、または認証方式が違う

401 の核心は「サーバーがあなたの身元を認めない」ことです。よくある原因は次のとおりです。

リクエストにキーがまったく付いていない、または環境変数が空。
ネイティブ API で x-goog-api-key ではなく Authorization を使っている。
OpenAI 互換 API で Authorization: Bearer ではなく x-goog-api-key を使っている。
キーの前後に空白や改行があり、コピー時に引用符が入った。
キーが削除、ローテーションされた、または所属プロジェクトが停止された。
ゲートウェイのキーを Google 公式アドレスに送った、またはその逆。
キーに API 制限が設定され、Gemini API の呼び出しが許可されていない。

まず最小リクエストで確認します。

export GEMINI_API_KEY="あなたのキー"

# Gemini ネイティブ API
curl "https://generativelanguage.googleapis.com/v1beta/models/<モデルID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"OK とだけ返してください"}]}]}'

# OpenAI 互換 API
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<モデルID>","messages":[{"role":"user","content":"OK とだけ返してください"}]}'

2 つのコマンドは 2 つの認証方式に対応します。どちらが通るかで、キーとアドレスがどちらの体系に属するか分かります。混用して 401 になるのは、キーが壊れているのではなく組み合わせが間違っているのです。

三、404：モデル名、パス、バージョンの誤り

404 は「モデルが存在しない」とは限りません。よくあるケースは次のとおりです。

モデル ID の綴りが違う、または API 識別子ではなくコンソールの表示名を使っている。
モデルが現在の API バージョンに属していない。たとえば新版でのみ公開されたモデルを旧版のパスに送っている。
Base URL の /v1、/v1beta が余分、または不足し、パス連結後に存在しないアドレスになった。
アドレス末尾にスラッシュが余分にあり、クライアントがさらにもう一度パスを連結した。
ゲートウェイ経由で呼び出す際、そのモデルが現在のグループやプランで開通していない。
チャット用 API で画像生成や他の専用 API を呼び出している。

切り分けでは、まず現在のキーで利用可能なモデルを一覧します。

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

一覧に対象モデルがあれば、次にリクエストパスを確認します。一覧になければ、先にモデルの開通または権限の問題を解決します。ゲートウェイ経由で呼び出す場合は、ゲートウェイのドキュメントが示すモデル ID と Base URL を基準とし、公式のモデル名をそのまま当てはめないでください。

四、429：レート制限かクォータ切れかを先に区別する

429 は最も誤判定されやすい種類です。少なくとも 3 つの状況を含みます。

種類	典型的な特徴	対応の方向性
分単位のレート制限	短時間の同時実行が高く、エラーが数秒内に集中	同時実行を下げ、バックオフして再試行
日次クォータの使い切り	当日の呼び出し量が上限に達し、失敗が継続	リセットを待つ、クォータを増やす、方式を変更
プロジェクト単位のクォータ	複数サービスが同じプロジェクトを共用し、互いに圧迫	プロジェクトとキーを分割し、クォータを個別化

エラー本文の details には通常、クォータ ID と推奨再試行時刻が示されます。429 を見てすぐ再送すると、再試行の嵐で状況が悪化します。まず依存関係をインストールします。pip install requests。利用可能なバックオフ処理の例を示します。

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<モデルID>:generateContent"
    headers = {
        "x-goog-api-key": "あなたのキー",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("再試行回数を使い切りました")

再試行で解決できるのは一時的な混雑だけで、クォータの使い切りは解決できません。本番環境ではタイムアウト、サーキットブレーカー、予備モデルも追加しないと、1 つの 429 が経路全体を止めてしまいます。

五、地域制限：中国国内からの直結が失敗する理由

Gemini API は一部の国と地域でのみ提供されています。リクエストの出口が非対応地域にある場合、よく 3 つの現れ方をします。

接続タイムアウトまたは TLS ハンドシェイク失敗。通常はネットワーク経路が通っていない。
400 FAILED_PRECONDITION を返し、メッセージに location is not supported のような文言が含まれる。
403 PERMISSION_DENIED を返す。プロジェクト、請求、地域権限に関係する場合がある。

ここで混同しやすい概念が 2 つあります。アカウントの登録地域とリクエストの出口地域です。アカウント自体が利用可能でも、サーバーが非対応地域に配備されていれば、リクエストは拒否される場合があります。逆に、ローカルのプロキシで Web ページが開けても、API リクエストが同じ経路を通っているとは限りません。

推奨する対応順序は次のとおりです。

リクエストがローカル、コンテナ、サーバーのどこから送られているかを確認し、実際の出口 IP を特定する。
出口地域が公式のサポート一覧に含まれるか照合する。
クラウドサーバーのリージョン選択を確認し、必要なら対応リージョンへ移す。
業務の中心が中国国内なら、コンプライアンスに沿ったゲートウェイ経由の接続を評価し、ネットワークと請求をまとめて扱う。
「IP を変える」だけを唯一の方法にせず、サービス条項と現地法令の要件を先に確認する。

六、その他の頻出エラー

現象	よくある原因	対応
400 INVALID_ARGUMENT	JSON 構造の誤り、ロール順序の誤り、画像形式の非対応	最小リクエストから項目を段階的に追加
400 FAILED_PRECONDITION	地域非対応、請求未開通、前提条件の欠落	地域、請求、プロジェクト状態を確認
403 PERMISSION_DENIED	API 未有効化、キー制限、プロジェクト権限不足	コンソールで有効化し、権限を確認
500 INTERNAL	上流の内部エラー	バックオフして再試行し、リクエスト ID を記録
503 UNAVAILABLE	上流の過負荷または保守	バックオフして再試行し、予備モデルに切り替え
応答はあるが内容がない	安全ポリシーによる遮断、出力の切断	blockReason と finishReason を確認
出力が途中で止まる	最大出力 Token に到達	上限を上げるか入力を短縮

「応答はあるが内容がない」は故障とみなされがちですが、実際には安全フィルターや長さ制限であることが多いです。返却された promptFeedback.blockReason、finishReason、usageMetadata を確認してから、プロンプトを変えるのかパラメータを調整するのかを決めます。

七、推奨する切り分け順序

完全なエラー JSON、リクエスト時刻、モデル ID、リクエスト ID を保存する。
curl で最小リクエストを送り、クライアントと SDK の影響を排除する。
Base URL、認証ヘッダー、モデル ID の 3 点を照合する。
動作が確認できている別のモデルに替え、モデル問題か経路問題かを判断する。
クォータ、請求、プロジェクト状態を確認し、429 と 403 を区別する。
リクエストの出口地域とネットワーク経路を確認する。
最後にクライアント設定、プロキシ設定、コード内の再試行ロジックを確認する。

一度に変更する変数は 1 つだけにします。そうしないと、復旧してもどの手順で直ったか分からず、次回も同じ問題を踏みます。

八、よくある質問

401 と 403 の違いは何ですか？

401 は「身元の検証に通らなかった」状態で、キー、認証ヘッダー、アドレスの一致を優先して確認します。403 は「身元は通ったが権限がない」状態で、API の有効化、プロジェクト権限、キー制限、地域ポリシーを優先して確認します。

429 は数分待って再試行すればよいですか？

クォータの種類によります。分単位のレート制限はバックオフ後に回復することが多いですが、日次クォータの使い切りはリセットを待つかクォータを増やす必要があります。エラー本文のクォータ ID と再試行の推奨を読み、むやみに再送しないでください。

地域制限は IP を変えれば解決しますか？

一概には言えません。実際の出口地域、アカウント状態、サービス条項によります。企業利用では、対応リージョンに配備するか、コンプライアンスに沿ったゲートウェイで統一的に接続するほうが安定します。

公式アドレスは通るのに、ゲートウェイに変えると 404 になるのはどちらの問題ですか？

まずゲートウェイの Base URL とモデル ID を確認します。ゲートウェイのモデル命名、パス、利用可能範囲は公式と異なる場合があり、公式のリクエストをそのまま当てはめられません。ゲートウェイのドキュメントにある最小サンプルで項目ごとに置き換えてください。

再試行でコストが膨らむのをどう防ぎますか？

最大再試行回数、指数バックオフ、タイムアウトを設定します。429 は個別に処理し、非冪等リクエストには重複排除を加え、ゲートウェイ側に予算上限とアラートを設定します。

次のステップ

Gemini のエラー切り分けで重要なのは、まず「認証、パス、クォータ、ネットワーク」の 4 種類を区別し、最小リクエストで項目ごとに検証することです。統一入口が必要で、中国国内からの直結の不確実性を減らしたい場合は、ZSQH AI Gateway に登録してください。モデル、クォータ、価格はモデル価格ページを基準とします。