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

> Gemini APIの429は短時間の制限か日次上限かで対処が変わります。403の利用資格・ファイル期限、400・404の設定確認、5xxの再試行を整理し、PythonとNode.jsで送信回数を制限する実装を紹介します。

- Source: https://www.aifreeapi.com/ja/posts/gemini-api-error-troubleshooting-guide
- Language: ja
- Published: 2026-03-17
- Updated: 2026-10-28
- Publisher: AI Free API (https://www.aifreeapi.com)

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

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

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

![Gemini APIのエラーを分類して確認先をたどるフローチャート](https://www.aifreeapi.com/posts/ja/gemini-api-error-troubleshooting-guide/img/error-decision-tree.webp)

| HTTPステータス | 最初に確認すること | 次の行動 |
|---|---|---|
| 400 | 不正な入力・未対応パラメータ・利用の前提条件 | エラー本文が示す項目を修正してから再送 |
| 401 | 認証情報が正しく送られているか | キーの設定と送信先を確認 |
| 402 | Prepayの残高不足など、支払いに関する条件 | 課金状況を確認。自動再試行は止める |
| 403 | プロジェクトへのアクセス・キー制限・ファイルの権限 | 拒否された対象を本文から特定 |
| 404 | モデル名・APIバージョン・リソースの存在 | 現行のモデル情報と参照先を照合 |
| 429 | 短時間の制限か、日次などの割り当て不足か | 前者は送信を抑制、後者はリセットや上限変更を検討 |
| 500・503 | 一時的なサーバーエラーか、同じ入力で繰り返すか | 回数を制限して再試行し、続く場合は入力や障害情報を確認 |
| 504 | サーバー処理の期限超過か | 入力・処理量とタイムアウトの設定を確認 |
| 501 | 使おうとしている機能が対応しているか | 対応する機能・モデル・APIに修正 |

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

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

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

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

| 確認する制限 | 状況の見分け方 | 対処の方向 |
|---|---|---|
| RPM：1分あたりのリクエスト数 | 小さいリクエストを同時に多数送っている | キューで送信を平準化し、同時実行数を減らす |
| 入力TPM：1分あたりの入力トークン数 | 回数が少なくても、長い入力をまとめて送っている | 不要な履歴を減らし、時間あたりの投入量を抑える |
| RPD：1日あたりのリクエスト数 | エラーの詳細が日次上限を示す | 日次リセットを待つか、利用可能な上限の変更を検討 |
| 支出額に基づく短時間の制限 | RPMやTPMだけでは説明できず、対象アカウントの制限に該当する | 適用されている支出ペースの上限と直近の利用を確認 |

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

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

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

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

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

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

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

## 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キーガイド](https://ai.google.dev/gemini-api/docs/api-key)

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

日本語で利用しているかどうかと、実行環境が対応地域にあるかどうかも別です。ローカルでは動き、海外のサーバーでは失敗する場合は、その実行場所が[対応地域](https://ai.google.dev/gemini-api/docs/available-regions)に含まれるか確認します。課金すれば地域条件も解消すると考えないでください。

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

Files APIにアップロードしたファイルは、[公式仕様では48時間後に自動削除](https://ai.google.dev/gemini-api/docs/files#delete-uploaded-files)されます。アプリ側のDBにファイルIDが残っていても、API側にファイルが残っているとは限りません。

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

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

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

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

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

生成パラメータの扱いはモデルごとに異なります。たとえば現行の公式ガイドでは、Gemini 3.6以降と4では`temperature`、`top_p`、`top_k`の独自設定を無視して警告し、将来のリリースでは400を返す予定としています。該当モデルではこれらの指定を外し、以前のGemini 3では既定値を保つ案内です。「temperatureを1.0にすれば400が直る」という共通ルールではありません。[モデルパラメータの確認事項](https://ai.google.dev/gemini-api/docs/troubleshooting#check-your-api-calls-for-model-parameter-errors)

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

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

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

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

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

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

![失敗後の待機時間を延ばしながら再試行する流れ](https://www.aifreeapi.com/posts/ja/gemini-api-error-troubleshooting-guide/img/retry-strategy.webp)

現在の公式SDKはPythonが`google-genai`、JavaScriptが`@google/genai`です。旧`google-generativeai`と`@google/generative-ai`を前提にした例は、[公式ライブラリ案内](https://ai.google.dev/gemini-api/docs/libraries)に沿って移行してください。

SDKに環境変数を自動検出させる場合、`GOOGLE_API_KEY`と`GEMINI_API_KEY`の両方があると、`GOOGLE_API_KEY`が優先されます。想定したキーと違うプロジェクトを使っていないか確認してください。以下の例では`GEMINI_API_KEY`を明示的に渡します。[環境変数の設定](https://ai.google.dev/gemini-api/docs/api-key)

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

`attempts=3`は**最初の送信を含めて最大3回**です。タイムアウトはミリ秒、待機時間は秒で指定します。30秒のタイムアウトは処理全体の30秒上限ではなく、再試行と待機によって合計時間は長くなります。この回数と時間は説明用の設定なので、利用者を待たせられる時間に合わせて調整してください。[Python SDKリファレンス](https://googleapis.github.io/python-genai/)・[JavaScriptの再試行設定](https://googleapis.github.io/js-genai/release_docs/interfaces/types.HttpRetryOptions.html)

### Python

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

```python
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にキーを埋め込まないでください。

```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クライアントも含め、どの層で何回再試行するかを決めてください。[公式の再試行方針](https://ai.google.dev/gemini-api/docs/troubleshooting#retry-strategy)

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

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

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

## よくある質問

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

一覧取得だけでは生成できるとは判断できません。`models.list`の200はキーの存在を確認しても、プロジェクトのティア資格や課金状態までは確認しないためです。生成の可否は別に確認する必要があります。[公式の説明](https://ai.google.dev/gemini-api/docs/troubleshooting#project-or-billing-account-policy-suspension)

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

同じプロジェクトの割り当て不足は直りません。レート制限はプロジェクト単位なので、まず上限に達した指標を確認します。漏洩・ブロックされたキーの交換とは別の対処です。[レート制限の適用単位](https://ai.google.dev/gemini-api/docs/rate-limits)

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

公式の課金FAQでは、400または500で失敗したリクエストはトークン料金が発生しない一方、割り当てにはカウントされると説明しています。これをすべてのエラーやタイムアウトに一般化することはできません。再試行で生成が成功した場合も含め、実際の利用明細で確認してください。[失敗したリクエストの課金](https://ai.google.dev/gemini-api/docs/billing#am-i-charged-for-failed-requests)

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

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