Gemini APIのエラー対処法：429・403・400・5xxを切り分ける

Gemini APIが失敗したときは、同じリクエストを送り直す前に、HTTPステータスとエラー本文を組み合わせて確認してください。 429でも、短時間の混雑と1日分の割り当てを使い切った状態では対処が違います。403もAPIキーだけが原因とは限らず、プロジェクトの利用資格や、期限切れのファイルを参照しているケースがあります。

ここで扱うのは、APIキーを使って呼び出すGemini Developer APIです。Geminiアプリ、Gemini CLI、Gemini Enterpriseの制限を、そのままDeveloper APIに当てはめることはできません。まず次の表で調べる場所を絞り、該当する手順へ進んでください。

エラーコードから最初の確認先を決める

HTTP番号と、レスポンス本文の識別子は別々に扱います。現在の公式APIエラー一覧では、Interactions APIのerror.codeにrate_limit_exceededやquota_exceededなどの文字列が使われます。一方、generateContentやSDKでは数値のコードやRESOURCE_EXHAUSTEDなどのステータス名を見ることがあります。すべての呼び出しを同じJSON形式で処理しないでください。

再現調査用には、発生日時とタイムゾーン、プロジェクト、モデルID、APIバージョン、SDKのバージョン、HTTPステータス、機密情報を除いたエラー内容、実際の送信回数を残します。APIキー、認証ヘッダー、プロンプト中の個人情報を丸ごとログに出す必要はありません。

429：待つ前に、どの上限に達したかを調べる

429を見てすぐに短い間隔で再送すると、残っている割り当てまで消費することがあります。エラー本文とAI Studioで対象プロジェクト・モデルの利用状況を照合し、制限の単位を確認します。

これらは公式のレート制限に基づく区分です。制限はAPIキーごとではなくプロジェクトごとに適用されます。同一プロジェクトでキーを追加しても割り当ては増えません。実際の上限はモデルやティアで異なるため、古い固定表よりも現在のプロジェクトに表示される値を優先してください。

RPDのリセットは太平洋時間の午前0時です。日本時間に直す場合は夏時間で変わるため、日付を含めてAmerica/Los_Angelesから換算します。また、アカウント条件によっては移動する10分間の支出額にも制限が適用されます。これは月額予算やPrepay残高とは別の確認項目です。支出額に基づく制限の説明で適用条件を確認してください。

使用量がほぼゼロなのに429になる場合

最初に、アプリが使っているキーのプロジェクトと、画面で見ているプロジェクトが一致しているか確認します。次にモデル、指標、表示期間を合わせ、エラー本文が示す上限と比較します。リクエスト数のグラフだけを見て、入力トークンや支出ペースの制限まで未使用だと判断しないことが大切です。

それでも説明できない場合は、機密情報を除いたエラー詳細と発生時刻を保存して調査に回します。「使用量がゼロだからGoogle側のバグ」「15分待てば必ず直る」とは判断できません。原因不明のまま再試行を増やすより、該当処理を一時停止したほうが、状況を追いやすくなります。

有料化を検討するタイミング

必要な処理量が現在の上限を継続的に超えるなら、有料ティアの条件と上限を確認する段階です。ただし、有料化で何倍になるか、混雑時にも必ず処理できるかは一律には言えません。入力・出力トークンから費用を見積もり、現在の料金と対象プロジェクトの上限を確認して判断します。

403：キー、プロジェクト、ファイルを分けて確認する

403で最初に読むべきなのは「何へのアクセスが拒否されたか」です。Your project has been denied accessならプロジェクト、キーの漏洩やブロックが明記されていればキー、Fileへの権限が記載されていれば参照ファイルを調べます。

キーそのものについては、種類とAPI制限も確認します。現在は無制限のstandard keyが拒否され、制限を設定したstandard keyは引き続き利用できます。2026年5月28日以降にAI Studioで新規作成されるキーはauth keyです。403対策として制限をすべて解除するのではなく、必要なGemini APIへのアクセスが許可されているかを確かめます。公式APIキーガイド

プロジェクトが無料枠の対象外である場合、同じプロジェクト内でキーを作り直しても利用資格は変わりません。公式ガイドでは、この場合は有効なCloud Billingアカウントを関連付け、有料ティアを利用するよう案内しています。有料化は無料枠を解放する操作ではなく、有料の利用に切り替える操作です。 未払い、プロジェクト停止、キーのブロックは復旧手順が異なるため、表示された理由に沿って進めます。プロジェクト制限に関する公式手順

日本語で利用しているかどうかと、実行環境が対応地域にあるかどうかも別です。ローカルでは動き、海外のサーバーでは失敗する場合は、その実行場所が対応地域に含まれるか確認します。課金すれば地域条件も解消すると考えないでください。

数日前は動いていたファイル付きリクエストが失敗する

Files APIにアップロードしたファイルは、公式仕様では48時間後に自動削除されます。アプリ側のDBにファイルIDが残っていても、API側にファイルが残っているとは限りません。

同じ認証情報でfiles.getを使い、対象ファイルの情報を取得できるか確認します。取得できない場合は、期限切れに加え、違うプロジェクトのファイルを参照していないかも確認してください。ファイルが必要な処理なら、元データを再アップロードし、新しい参照先に更新します。

日本語のファイル参照による403の事例でも、数日後に古いファイルIDを送って失敗した経緯が紹介されています。これは403の一例であり、すべての403がファイル期限によるものではありません。また、必須資料を黙って外してテキストだけで実行すると、APIエラーが消えても依頼された処理は完了しません。資料を復元するか、処理できないことを利用者に伝えます。

400・404：最小の入力に戻してモデルと設定を照合する

400では、エラー本文が指している入力項目を修正します。まずテキストだけの短い入力にし、ツール、添付ファイル、独自の生成設定を一度外します。それが成功するなら、必要な設定を一つずつ戻すことで、失敗する組み合わせを絞れます。この確認も実際のAPI利用になるため、課金や割り当ての消費を伴う点は変わりません。

モデルの対応機能とAPIバージョンも一致させます。古い記事のモデル名をそのまま置き換えるのではなく、モデル一覧と廃止・移行情報で、使用するモデルが現在のプロジェクトで利用できるかを確認してください。404なら、モデルIDの誤記だけでなく、削除済みのファイルなど、参照リソースにも目を向けます。

生成パラメータの扱いはモデルごとに異なります。たとえば現行の公式ガイドでは、Gemini 3.6以降と4ではtemperature、top_p、top_kの独自設定を無視して警告し、将来のリリースでは400を返す予定としています。該当モデルではこれらの指定を外し、以前のGemini 3では既定値を保つ案内です。「temperatureを1.0にすれば400が直る」という共通ルールではありません。モデルパラメータの確認事項

400の内容がFAILED_PRECONDITIONなど利用条件を示しているなら、JSONを直す作業では解決しません。課金・地域・利用資格のどの条件が満たされていないかを確認します。

500・503・504：再試行に上限を設け、続くなら調査へ戻る

500や503が一時的に発生した場合は、待機時間を延ばしながら、回数を決めて再試行できます。503はサービスが利用できない状態、504は処理の期限超過を示します。ただし、何秒待てば復旧するかをエラー番号だけで決めることはできません。公式APIエラー一覧

Geminiのステータスページで障害情報を確認しつつ、短い入力でも失敗するかを切り分けます。特定の長い入力だけが失敗するなら、内容を分割するなど処理量を減らして比較します。ステータスページに障害が載っていないことだけでは、そのリクエストに問題がないとは言えません。

クライアント側のタイムアウトを延ばすと改善するのは、クライアントが先に待機を打ち切っている場合です。サーバーが返す504の期限を、クライアント設定だけで延長できるとは限りません。また、タイムアウトした時点では、サーバーが処理を実行していないと断定できません。再送する設計では、生成結果の重複保存や後続処理の二重実行も防ぐ必要があります。

Python・Node.jsで再試行の回数を制限する

現在の公式SDKはPythonがgoogle-genai、JavaScriptが@google/genaiです。旧google-generativeaiと@google/generative-aiを前提にした例は、公式ライブラリ案内に沿って移行してください。

SDKに環境変数を自動検出させる場合、GOOGLE_API_KEYとGEMINI_API_KEYの両方があると、GOOGLE_API_KEYが優先されます。想定したキーと違うプロジェクトを使っていないか確認してください。以下の例ではGEMINI_API_KEYを明示的に渡します。環境変数の設定

以下は、500・503・504だけをSDKに再試行させる最小例です。429は日次上限と短時間の制限を区別する必要があるため、ここでは自動再試行せず呼び出し元へ返します。運用側で短時間の制限と確認できた場合に、待機やキュー投入を別途判断してください。

attempts=3は最初の送信を含めて最大3回です。タイムアウトはミリ秒、待機時間は秒で指定します。30秒のタイムアウトは処理全体の30秒上限ではなく、再試行と待機によって合計時間は長くなります。この回数と時間は説明用の設定なので、利用者を待たせられる時間に合わせて調整してください。Python SDKリファレンス・JavaScriptの再試行設定

Python

仮想環境でpip install google-genai==2.33.0を実行し、サーバーの環境変数GEMINI_API_KEYにキー、GEMINI_MODELに利用可能なモデルIDを設定します。次の内容をgemini_request.pyとして保存し、python gemini_request.pyで実行できます。実行時には実際の生成リクエストが送信されます。

import os
import sys
from google import genai
from google.genai import errors, types


def main():
    with genai.Client(
        api_key=os.environ["GEMINI_API_KEY"],
        http_options=types.HttpOptions(
            timeout=30_000,
            retry_options=types.HttpRetryOptions(
                attempts=3,
                initial_delay=1.0,
                max_delay=8.0,
                exp_base=2.0,
                jitter=1.0,
                http_status_codes=[500, 503, 504],
            ),
        ),
    ) as client:
        try:
            response = client.models.generate_content(
                model=os.environ["GEMINI_MODEL"],
                contents="疎通確認です。短く返答してください。",
            )
        except errors.APIError as exc:
            print(f"生成に失敗しました。HTTPコード: {exc.code}", file=sys.stderr)
            raise SystemExit(1) from None
        if not response.text:
            raise RuntimeError("テキストがありません。終了理由やブロック情報を確認してください。")
        print(response.text)


if __name__ == "__main__":
    main()

Node.js

Node.jsのプロジェクトでnpm install @google/genai@2.31.0を実行します。同じ2つの環境変数を設定し、次をgemini-request.mjsに保存してnode gemini-request.mjsで実行してください。ブラウザへ配信するJavaScriptにキーを埋め込まないでください。

import { GoogleGenAI, ApiError } from "@google/genai";

async function main() {
  const apiKey = process.env.GEMINI_API_KEY;
  const model = process.env.GEMINI_MODEL;
  if (!apiKey || !model) {
    throw new Error("GEMINI_API_KEYとGEMINI_MODELを設定してください。");
  }
  const ai = new GoogleGenAI({
    apiKey,
    httpOptions: {
      timeout: 30_000,
      retryOptions: {
        attempts: 3,
        initialDelay: 1,
        maxDelay: 8,
        expBase: 2,
        jitter: 1,
        httpStatusCodes: [500, 503, 504],
      },
    },
  });
  const response = await ai.models.generateContent({
    model,
    contents: "疎通確認です。短く返答してください。",
  });
  if (!response.text) {
    throw new Error("テキストがありません。終了理由やブロック情報を確認してください。");
  }
  console.log(response.text);
}

main().catch((error) => {
  if (error instanceof ApiError) {
    console.error(`生成に失敗しました。HTTPコード: ${error.status}`);
  } else {
    console.error("生成を完了できませんでした。設定・通信・応答内容を確認してください。");
  }
  process.exitCode = 1;
});

掲載例はPython SDK 2.33.0とJavaScript SDK 2.31.0を使い、外部通信を行わない模擬応答で確認しています。成功、503からの復帰、上限回数での停止、400・403・429を再送しない動作を確認するもので、実際のAPIアクセス権や障害からの復旧を実証するテストではありません。

SDKの外側にもリトライ用ループを置くと、送信回数が掛け算で増えることがあります。たとえばSDKが最大3回、外側が最大3回なら、1件の処理で最大9回送る設計になり得ます。ジョブ基盤やHTTPクライアントも含め、どの層で何回再試行するかを決めてください。公式の再試行方針

解消しないときに残す情報と、利用者への返し方

同じ入力で失敗が続く場合は、再試行の回数を増やす前に、最小の再現条件を保存します。調査担当者が同じ状況を理解できるよう、モデル・API・SDKのバージョン、発生時刻、機密情報を除いたエラー内容、最初の失敗と再試行を含む送信回数をまとめます。成功する短い入力との差分も役立ちます。

利用者には処理が完了していないことを伝えます。日次上限なら受付を止めるか後で実行するキューへ回し、一時的な障害なら再操作できる状態にします。別モデルへの切り替えやキャッシュ利用を行う場合も、必要な機能、情報の鮮度、費用が変わる点を踏まえて設計してください。

よくある質問

モデル一覧を取得できれば、APIキーに問題はありませんか？

一覧取得だけでは生成できるとは判断できません。models.listの200はキーの存在を確認しても、プロジェクトのティア資格や課金状態までは確認しないためです。生成の可否は別に確認する必要があります。公式の説明

429はAPIキーを作り直せば直りますか？

同じプロジェクトの割り当て不足は直りません。レート制限はプロジェクト単位なので、まず上限に達した指標を確認します。漏洩・ブロックされたキーの交換とは別の対処です。レート制限の適用単位

失敗したリクエストにも料金がかかりますか？

公式の課金FAQでは、400または500で失敗したリクエストはトークン料金が発生しない一方、割り当てにはカウントされると説明しています。これをすべてのエラーやタイムアウトに一般化することはできません。再試行で生成が成功した場合も含め、実際の利用明細で確認してください。失敗したリクエストの課金

ステータスコードが200なのにテキストが空です。再試行すべきですか？

HTTP通信の成功と、必要な生成結果を得られたことは別です。まずレスポンスの終了理由、ブロック情報、返却された内容の種類を確認します。安全性によるブロックや非テキスト出力を、ネットワーク障害として何度も再送しないでください。APIエラー・生成ブロックのリファレンス