Gemini APIエラー完全解決ガイド：429・400・403・500の修正方法【2026年版】

Gemini APIのエラーは、まったく異なる対処が必要な2つのカテゴリに分かれます。リトライ可能なエラー（429、500、503、504）は待ってから再試行すれば最終的に成功するもので、リトライ不可のエラー（400、403、404）はリクエストのコードや設定を変更しない限り成功しないものです。この区別を理解することがAPIエラー処理で最も重要な概念であり、間違えると「絶対に成功しないリクエストを無駄にリトライし続ける」か「少し待てば成功するリクエストを諦めてしまう」ことになります。本ガイドでは、遭遇するすべてのエラーを網羅し、そのままプロジェクトにコピーできる実用コードを提供します。

要点まとめ

すべてのGemini APIエラーは2つの戦略のいずれかに対応します。指数バックオフでリトライ(429、500、503、504の場合)または修正して再デプロイ（400、403、404の場合）です。429 RESOURCE_EXHAUSTEDエラーは2026年の開発者からの苦情の約90%を占めており、その主な原因はGoogleが2025年12月に無料枠のレート制限を50〜80%削減したことです。無料枠で429エラーが発生している場合、最も早い解決策は課金を有効にしてTier 1の制限を解除することで、通常は即座に反映されます。サーバーエラー（500/503）の場合は、自分のコードをデバッグする前にGoogle AIステータスページを確認してください。以下の表は、すべてのエラーコードのクイックリファレンスです。

トラブルシューティング診断フローチャート

Gemini APIリクエストが失敗した場合、HTTPステータスコードがどの診断パスを辿るべきかを正確に示してくれます。最も重要な最初のステップは、ステータスコードだけでなくエラーレスポンスのボディ全体を読むことです。すべてのGemini APIエラーは、gRPCエラー名を含むstatusフィールドと、問題を直接指摘する人間が読めるの詳細を含むmessageフィールドを持つJSONオブジェクトを返します。多くの開発者がHTTPレベルで例外をキャッチし、この詳細を破棄してしまうミスを犯しており、5分で解決できる問題が1時間の推測作業になってしまいます。

診断の手順は以下の通りです。 まず、ステータスコードが4xx範囲か5xx範囲かを確認します。4xxの場合、問題はクライアント側にあり、リトライしても解決しません。エラーメッセージを確認し、リクエストの何が間違っているかを特定して修正し、再度試す必要があります。5xxの場合、問題はGoogle側にある可能性が高いです。ステータスページを確認し、サービスが正常であれば指数バックオフでリトライロジックを実装してください。この明確な区分の唯一の例外が429エラーで、技術的には4xxコードですが、十分に待つかリクエストレートを減らせば自然に解消する一時的なエラーのように振る舞います。

各エラータイプについて、以下の手順に従ってください。 まず、ヘッダーを含むエラーレスポンス全体をログに記録します。特に429エラーの場合はRetry-Afterヘッダーに注目してください。次に、ログで同じエラーを以前にも見たことがあるか確認します。同じエンドポイントで繰り返し発生する400エラーはリクエスト構築方法の体系的な問題を示唆し、散発的な429エラーはクライアントコードにレート制限が必要なことを示唆します。デプロイ後に一貫して発生する403エラーは環境変数やシークレット管理の問題を示唆します。これらのパターンを理解することで、デバッグ時間を大幅に節約できます。Gemini CLIを使用していて429エラーが頻発する場合、CLIにはAPI直接呼び出しとは別の独自のレート制限動作があることに注意してください。詳細はGitHubのgemini-cli issue #10722に記載されています。

429 RESOURCE_EXHAUSTED エラーの徹底解説（最も一般的なエラー）

429 RESOURCE_EXHAUSTEDエラーはGemini APIで最も頻繁に発生するエラーであり、Googleが2025年12月6〜7日に無料枠のレート制限を50〜80%削減した後にその発生率が急増しました。この変更前、Gemini 2.0 Flashは無料枠で10 RPMを提供していましたが、変更後は5 RPMに低下し、全モデルで1日あたりのリクエスト制限も同様に削減されました。この変更は公式チャネルを通じて発表されず、数千人の開発者が不意打ちを受けました。2025年11月までアプリケーションが正常に動作していたのに、コード変更なしで12月から429エラーが発生するようになった場合、ほぼ確実にこれが原因です。

Gemini APIは3つの独立した次元で使用量を測定しており、いずれか1つを超過すると429エラーが発生します。これらの次元はRPM（1分あたりのリクエスト数）、TPM（1分あたりの入力トークン数）、RPD（1日あたりのリクエスト数）です。つまり、RPM制限内であっても、いくつかの大きなリクエストがTPMしきい値を超えてしまうとスロットリングされる可能性があります。2026年3月17日時点の公式ドキュメントで確認した現在の無料枠制限は以下の通りです。

出典: ai.google.dev/gemini-api/docs/rate-limits、2026-03-17検証

レート制限はAPIキーごとではなくプロジェクトごとに適用されます。これは多くの開発者を混乱させる重要な違いです。同じGoogle Cloudプロジェクト内で複数のAPIキーを作成しても、追加のクォータは得られません。より多くの容量が必要な場合は、別のプロジェクト（制限を回避する目的での作成はGoogleの利用規約違反です）か、有料ティアへのアップグレードが必要です。

どの制限に達したかの診断方法

429エラーを受信した場合、レスポンスメッセージには通常どの制限を超過したかが記載されていますが、常に明確とは限りません。ボトルネックを体系的に特定する方法は以下の通りです。まず、Google Cloud ConsoleのAPIs & Services > Gemini API > Quotasで使用状況を確認します。RPM使用量が急増してTPMが低い場合、小さなリクエストが多すぎるためバッチ処理を検討してください。TPMが急増してRPMが中程度の場合、リクエストに含まれる入力データが多すぎるためコンテキスト長を短縮するか、より小さなモデルに切り替えてください。RPDが制限要因の場合、1日の上限に達しているため、太平洋時間の深夜のリセットを待つか、ティアをアップグレードする必要があります。

「ゴースト429」問題

2026年初頭、有料のTier 1アカウントの複数の開発者が、使用量ダッシュボードがゼロまたはゼロに近い消費量を示しているにもかかわらず429 RESOURCE_EXHAUSTEDエラーを受信する報告をしました。この「ゴースト429」現象は、Googleのクォータ追跡システムのサーバー側バグのようです。これが発生している場合、まずダッシュボードが正しいプロジェクトを参照しているか確認してください。次に、バッチAPIジョブが実行中でないか確認してください。バッチ操作はリアルタイムダッシュボードに表示されない別のクォータを消費します。どちらにも該当しない場合、15〜30分待つことがコミュニティでの一般的な対処法です。1時間以上続く場合は、Google AI Developers Forumを通じてサポートチケットを提出してください。Google AI Developers Forumのこのレポートで、複数の開発者が回避策を共有しています。

アップグレードせずに429エラーを減らす実践的な方法

有料ティアへのアップグレードがすぐには難しい場合、いくつかの最適化戦略で無料枠での429エラー発生率を劇的に削減できます。最も効果的なアプローチはリクエストバッチングで、複数の小さなリクエストをより少ない大きなリクエストにまとめます。無料枠はTPMよりもRPMをより厳しく制限するため、10個の質問を含む1つのリクエストを送信する方が、10個の個別リクエストを送信するよりもはるかに効率的です。Gemini APIは1つのリクエスト内でマルチターン会話をサポートしており、この最適化の実装は簡単です。

もう1つの強力なテクニックはクライアント側のレート制限で、APIの制限よりも厳しい制限をアプリケーション自体に設けて安全マージンを維持します。無料枠のGemini 2.5 Flashが10 RPMを許可している場合、クライアントを1分あたり最大8リクエストに設定します。このバッファがタイミングのばらつきを吸収し、バースト時に最後のリクエストで制限に達するイライラするパターンを防ぎます。シンプルなトークンバケットやスライディングウィンドウアルゴリズムで実装できます。連続するリクエスト間に100〜300ミリ秒の遅延を追加するだけでも、バースト関連の429エラーを防ぐのに十分な場合が多いです。

より高いレイテンシを許容できるアプリケーションの場合、Batch APIはクォータ管理に根本的に異なるアプローチを提供します。バッチリクエストには独自のレート制限（100の同時リクエスト、2GBの入力ファイル制限）があり、非同期で処理されるため、リアルタイムAPI呼び出しとクォータを競合しません。Googleは即時応答を必要としないワークロード（データ処理パイプライン、コンテンツ生成キュー、評価タスクなど）にBatch APIを明示的に推奨しています。適切なユースケースでは429エラーを完全に排除できる、見落とされがちなソリューションです。

429エラーに特化した高度な最適化テクニックを含む詳細ガイドについては、429 RESOURCE_EXHAUSTED修正詳細ガイドをご覧ください。全ティア・全モデルのレート制限の包括的な内訳については、ティア別レート制限完全ガイドをご参照ください。

400・403エラーの修正方法（リトライ不可）

429エラーとは異なり、400・403エラーはリクエストまたは認証の根本的な問題を示しており、待っても解決しません。変更なしにこれらのエラーをリトライすることは無意味で、時間とAPIクォータの両方を浪費します。

400 INVALID_ARGUMENT ― リクエストが不正

ステータスINVALID_ARGUMENTの400エラーは、Gemini APIがリクエストを受信したものの、リクエストボディの何かが間違っているため処理できなかったことを意味します。最も一般的な原因は、サポートされていないパラメータ値の送信、特定モデルの最大出力トークン制限の超過、無効なtemperatureまたはtopP値の指定、存在しないか廃止されたモデル名の参照です。

多くの開発者を困惑させる具体例を紹介します。Gemini 3.xモデルでは、temperatureパラメータをデフォルト値の1.0に維持する必要があります。Gemini 2.5モデルでは問題なく動作する0.2や0.7に設定すると、Gemini 3モデルではループや性能低下を引き起こし、400エラーが発生する場合があります。APIリファレンスドキュメントでモデル固有のパラメータ制約を必ず確認してください。400エラーの修正は一貫したパターンに従います。エラーメッセージを注意深く読み、リクエストパラメータをドキュメントと比較し、不一致を修正することです。

python

# NG - Gemini 3 Pro Previewは2026年3月9日にシャットダウン
model = "gemini-3-pro-preview"

# OK - 現行モデルを使用
model = "gemini-2.5-flash"

# よくある400エラー: モデルに対して無効なパラメータ
# NG - Gemini 3.xではtemperature < 1.0で問題が発生する可能性
config = {"temperature": 0.3}

# OK - Gemini 3.xではデフォルトのtemperatureを使用
config = {"temperature": 1.0}

400 FAILED_PRECONDITION ― リージョンまたは課金の制約

この400エラーのバリアントは、アカウントがAPIを使用するための前提条件を満たしていないことを意味します。最も一般的な2つの原因は、課金を有効にせずにサポートされていないリージョンから操作していること、および有料ティアが必要な機能を使用しようとしていることです。このエラーが表示された場合、Google AI Studioにアクセスし、プロジェクトで課金が有効になっているか確認してください。課金を有効にすると、実際にお金を使う予定がなくても、プロジェクトが無料枠からTier 1にアップグレードされるため、多くの場合すぐに解決します。

403 PERMISSION_DENIED ― 認証とアクセスの問題

403エラーは、サーバーがリクエストを理解したものの認可を拒否していることを意味します。これはほぼ常にAPIキーの問題です。一般的な原因には、間違ったプロジェクトのAPIキーの使用、失効したキーまたは漏洩が検出されブロックされたキーの使用（Googleは公開リポジトリで検出された漏洩キーを事前にブロックします）、Google CloudプロジェクトでGenerative Language APIが有効になっていないこと、チューニングされたモデルに適切な認証なしでアクセスしようとしていることが含まれます。

ブラウザベースのアプリケーションからAPIにアクセスする際に403エラーが発生する場合、複数のGoogleアカウントのサインインが認証の競合を引き起こす可能性があることに注意してください。ブラウザが、個人アカウントにAPIアクセスがあるにもかかわらず、APIアクセス権のない業務用アカウントの認証情報で認証しようとする場合があります。修正方法は、すべてのGoogleアカウントからサインアウトし、APIアクセスが有効なアカウントのみでサインインし直すことです。Googleのサポートフォーラムでも言及されている、驚くほど一般的な問題です。認証のトラブルシューティングの詳細については、関連する認証情報の問題を深く掘り下げた401認証エラートラブルシューティングガイドをご覧ください。

堅牢なリトライロジックの構築

リトライロジックは一時的なエラー（429、500、503、504）に対する最初の防御線です。基本原則は指数バックオフです。短い遅延から始め、失敗するたびに遅延を2倍にし、すべてのクライアントが同時にリトライすることを防ぐための小さなランダムジッターを追加します。以下は、すべてのリトライ可能なGemini APIエラーを処理するPythonの本番対応実装です。

python
import time
import random
import google.generativeai as genai
from google.api_core import exceptions

def call_gemini_with_retry(
    model_name: str,
    prompt: str,
    max_retries: int = 5,
    base_delay: float = 1.0,
    max_delay: float = 60.0
):
    """指数バックオフリトライロジックでGemini APIを呼び出します。"""
    model = genai.GenerativeModel(model_name)

    for attempt in range(max_retries):
        try:
            response = model.generate_content(prompt)
            return response

        except exceptions.ResourceExhausted as e:
            # 429 - レート制限
            delay = min(base_delay * (2 ** attempt), max_delay)
            jitter = random.uniform(0, delay * 0.1)
            wait_time = delay + jitter
            print(f"レート制限 (試行 {attempt + 1}/{max_retries})。"
                  f"{wait_time:.1f}秒待機中...")
            time.sleep(wait_time)

        except exceptions.InternalServerError:
            # 500 - サーバーエラー
            delay = min(base_delay * (2 ** attempt), max_delay)
            jitter = random.uniform(0, delay * 0.1)
            print(f"サーバーエラー (試行 {attempt + 1}/{max_retries})。"
                  f"{delay + jitter:.1f}秒後にリトライ...")
            time.sleep(delay + jitter)

        except exceptions.ServiceUnavailable:
            # 503 - サービス利用不可
            wait_time = min(30 * (2 ** attempt), 300)
            print(f"サービス利用不可。{wait_time}秒待機中...")
            time.sleep(wait_time)

        except exceptions.InvalidArgument as e:
            # 400 - リトライ不可、リクエストを修正
            raise RuntimeError(f"無効なリクエスト（リトライ不可）: {e}")

        except exceptions.PermissionDenied as e:
            # 403 - リトライ不可、認証情報を修正
            raise RuntimeError(f"権限拒否（リトライ不可）: {e}")

    raise RuntimeError(f"{max_retries}回の試行後に失敗")

同じロジックをNode.jsでGoogle公式Generative AI SDKを使用して実装すると以下のようになります。

javascript
const { GoogleGenerativeAI } = require("@google/generative-ai");

async function callGeminiWithRetry(modelName, prompt, maxRetries = 5) {
  const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
  const model = genAI.getGenerativeModel({ model: modelName });

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await model.generateContent(prompt);
      return result.response.text();

    } catch (error) {
      const status = error.status || error.httpStatusCode;

      // リトライ不可のエラー — 即座に失敗
      if ([400, 403, 404].includes(status)) {
        throw new Error(`リトライ不可のエラー ${status}: ${error.message}`);
      }

      // リトライ可能なエラー — 待機してリトライ
      if ([429, 500, 503, 504].includes(status)) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 60000);
        const jitter = Math.random() * delay * 0.1;
        console.log(`エラー ${status}、試行 ${attempt + 1}/${maxRetries}。`
                   + `${((delay + jitter) / 1000).toFixed(1)}秒待機中...`);
        await new Promise(r => setTimeout(r, delay + jitter));
        continue;
      }

      throw error; // 不明なエラー、リトライしない
    }
  }
  throw new Error(`${maxRetries}回の試行後に失敗`);
}

多くのリトライ実装が間違える3つの重要なポイントがあります。 第一に、400や403エラーを絶対にリトライしないでください。これらはコードや設定の問題を示しており、時間が経っても解決しません。リトライするとクォータを浪費し、本来の修正を遅らせるだけです。第二に、遅延にランダムジッターを追加してください。ジッターなしでは、同時にレート制限に達したすべてのクライアントが同時にリトライし、別の429エラーのラウンドを引き起こす「サンダリングハード」が発生します。第三に、最大遅延上限を設定してください。上限のない指数バックオフは、数回の失敗後に途方もなく長い待ち時間を生み出す可能性があります。インタラクティブなアプリケーションでは通常60秒が妥当な上限です。

500・503サーバーエラーの処理

サーバーエラー（5xx）は、あなたのコードではなくGoogleのインフラで問題が発生したことを意味します。正しい対応はほぼ常に遅延を置いてからリトライすることですが、各エラータイプには対応方法に影響する重要なニュアンスがあります。

500 INTERNALエラーは本当に一時的な場合もあれば、入力がモデルで処理するには大きすぎることを示している場合もあります。同じリクエストで一貫して500エラーが発生するが他のリクエストは問題なく動作する場合、入力コンテキスト長を減らしてみてください。Gemini APIのドキュメントでは、過度に長い入力コンテキストが500エラーの既知のトリガーであると記載されています。特に100万トークンのコンテキストウィンドウをサポートするモデルで顕著です。大きなドキュメントを処理する場合、すべてを1回のリクエストで送信するのではなく、より小さなチャンクに分割して複数のリクエストを行うことを検討してください。

503 UNAVAILABLEエラーは通常、Geminiサービスが高負荷状態にあることを示します。ピーク使用期間やモデルのロールアウト時に発生しやすくなります。503に遭遇した場合、最初のアクションはGoogle Cloudステータスダッシュボードで既知のインシデントがないか確認することです。インシデントがある場合、待つしかありません。ステータスページですべてのサービスが正常と表示されている場合、429エラーで使用する1秒の初期遅延ではなく、30秒からの長い初期遅延でリトライロジックを実装してください。

504 DEADLINE_EXCEEDEDエラーはリクエストの処理がサーバーのタイムアウトで許可された時間を超えたことを意味します。最も一般的な原因は非常に大きなプロンプトや、広範なモデル計算を引き起こすリクエスト（Gemini 2.5 Proの思考モードでの複雑な推論タスクなど）です。修正方法は通常、クライアント側のタイムアウト設定を延長することです。Python SDKを使用している場合はtimeoutパラメータを渡せます。HTTPリクエストを直接行っている場合は、大きなリクエストに対してHTTPクライアントのタイムアウトを少なくとも120秒に調整してください。タイムアウトを延長しても504エラーが続く場合、リクエストごとのタイムアウト制約がないBatch APIへの切り替えを検討してください。

エラーパターンの監視ダッシュボード構築

エラーパターンを時間経過とともに理解することは、個別のエラーをデバッグするよりもはるかに価値があります。すべてのAPIレスポンスのステータスコード、レイテンシ、トークン数をログに記録するシンプルな監視セットアップは、一回限りのデバッグでは見えないパターンを明らかにできます。例えば、429エラーが特定の時間帯に集中する場合、ピーク時にリージョン内の他のユーザーと競合している可能性があります。500エラーが特定のプロンプト長と相関する場合、コンテキストウィンドウの境界問題を特定できます。

最も実用的なアプローチは、後でクエリできる構造化フォーマットでAPIレスポンスをログに記録することです。すべてのログエントリにタイムスタンプ、HTTPステータスコード、エラーメッセージ、モデル名、入力トークン数、レスポンスレイテンシを含めてください。シンプルなCSVファイルやSQLiteデータベースでも、トレンドを把握するのに十分な構造を提供します。多くの開発者は、429エラーの大半が予想外に高いリクエストボリュームを生成する単一の機能やエンドポイントから発生していることを発見し、その1つのボトルネックを修正するだけでエラーの大半を排除できます。マネージドソリューションを好む場合、Google Cloud Operations（旧Stackdriver）はCloud Consoleを通じてGemini APIの使用状況を自動的に監視できますが、これにはプロジェクトをGoogle Cloud課金アカウントにリンクする必要があります。

アップグレードの判断基準 ― 無料枠 vs 有料ティアの分析

無料枠から有料ティアへのアップグレードの判断は、コスト構造を理解すれば明快です。Gemini APIはティア制を採用しており、累計支出額が増えるとレート制限が自動的に引き上げられます。2026年3月17日時点の公式ドキュメントで確認した各ティアの仕組みは以下の通りです。

出典: ai.google.dev/gemini-api/docs/rate-limits、2026-03-17検証

無料からTier 1へのアップグレードは最もインパクトのある変更です。 課金アカウントを有効化するだけで、まだお金を使っていなくても、通常は無料枠の10〜20倍のTier 1制限がすぐに解除されます。アップグレードは即座に反映されます。429エラーが定期的に発生している場合、この1つのステップでほとんどのケースが解決します。なお、2026年4月1日からGoogleはティアの支出上限を強制し始めるため、アカウントに適用される可能性のある新しい制限について課金ドキュメントを確認してください。

本番ワークロードでTier 1の制限でも不十分な場合、laozhang.aiのような統合APIゲートウェイを検討してください。複数のプロバイダーにまたがるリクエストを集約し、プロバイダーごとのスロットリングなしでより高いレート制限を提供します。このアプローチは、単一プロバイダーの制限を超えるバーストトラフィックパターンをサポートする必要がある場合に特に有用です。プロバイダー間のレート制限をどのように透過的に処理するかはdocs.laozhang.aiで確認できます。全ティア・全モデルのGemini API料金の完全な内訳については、Gemini API料金・クォータガイドをご覧ください。無料枠の制限については、無料枠レート制限ガイドで詳しく比較できます。

個人開発者向けのコスト現実チェック。 最もコストパフォーマンスに優れたモデルであるGemini 2.5 Flashの有料ティア価格は、100万入力トークンあたり0.30ドル、100万出力トークンあたり2.50ドルです（ai.google.dev/gemini-api/docs/pricing、2026-03-17検証）。1日1,000リクエスト、平均的なプロンプトサイズの典型的なアプリケーションの場合、月額コストは出力長に応じて約5〜15ドルです。実際の価値を生み出すアプリケーションにとっては些末なコストであり、429エラーの排除による信頼性の向上はこの費用を十分に正当化します。Gemini 2.5 Flash-Liteバリアントは100万入力トークンあたり0.10ドルとさらに安い選択肢を提供しており、最高品質が重要でないアプリケーションに適しています。

複数のAIプロバイダー（Gemini、OpenAI、Anthropicなど）に単一のエンドポイントからアクセスする必要がある本番アプリケーションを構築するチームにとって、laozhang.aiのような統合APIゲートウェイはインフラを簡素化しながら、組み込みのレート制限、負荷分散、プロバイダー間の自動フェイルオーバーを提供できます。これは、スロットリングされている同じエンドポイントに対して単純にリトライするのではなく、レート制限に達した時に別のプロバイダーにフォールバックしたい場合に特に有用です。

2026年のモデル変更がエラー処理に与える影響

Geminiのモデル環境は2026年初頭に大きく変化し、これらの変更のいくつかがエラー処理に直接影響を与えています。コード変更なしで最近エラーが発生するようになった場合、以下のモデル移行のいずれかが原因かもしれません。

Gemini 3 Pro Previewは2026年3月9日に廃止・シャットダウンされました。 コードがgemini-3-pro-previewや類似のプレビューモデル名を参照している場合、400 INVALID_ARGUMENTエラーまたは404 NOT_FOUNDエラーが発生します。推奨される移行パスはgemini-3.1-pro-previewまたは安定版のgemini-2.5-proを使用することです。プレビューモデルは本質的にこのリスクを伴うため、本番アプリケーションでは常に利用可能な安定版モデルをターゲットにすべきです。

Gemini 2.0 Flashは廃止され、2026年6月1日にシャットダウン予定です。 現在gemini-2.0-flashまたはgemini-2.0-flash-liteを使用している場合、期限までにgemini-2.5-flashまたはgemini-2.5-flash-liteへの移行を計画してください。新しいモデルは同等以下のコストでより良いパフォーマンスを提供しますが、設定がモデル固有のデフォルトに依存していた場合、パラメータの動作がわずかに異なり400エラーが発生する可能性があります。

Gemini Embedding 2が初の完全マルチモーダル埋め込みモデルとして発表されました。 RAGアプリケーションを構築している場合、この新モデルは異なるコンテンツタイプの埋め込み時の入力形式の不一致に関するエラーを削減できる可能性があります。現在のモデルラインナップには、Gemini 3.1 Pro Preview、3.1 Flash-Lite Preview、3 Flash Preview、および完全なGemini 2.5ファミリー（Pro、Flash、Flash-Lite）とそのTTSバリアントが含まれます。本番コードで使用する前に、公式モデルリストで正確なモデル名文字列を必ず確認してください。モデル名のわずかなタイプミスでも404エラーが発生します。

FAQ ― Gemini APIエラーに関するよくある質問

Gemini API 429 Too Many Requestsエラーの修正方法は？

最速の修正はリクエスト間に遅延を追加することで、100〜300ミリ秒でも高頻度バーストの防止に十分な場合が多いです。長期的な解決策としては、指数バックオフリトライロジックを実装してください（上記のリトライセクションのPythonとNode.jsのコード例を参照）。無料枠で429エラーが定期的に発生する場合、課金を有効にしてTier 1にアップグレードすると、レート制限が即座に10〜20倍に増加します。

Gemini APIで403 PERMISSION_DENIEDエラーが発生する原因は？

403エラーはほぼ常にAPIキーの問題を示します。最も一般的な原因は、Gemini APIが有効になっているプロジェクトとは異なるGoogle CloudプロジェクトのAPIキーを使用していること、公開リポジトリで検出されGoogleがブロックしたキーを使用していること、プロジェクトでGenerative Language APIが有効になっていないこと、複数のGoogleアカウントがサインインしている場合のブラウザ認証の競合です。Google AI Studioでキーを確認し、必要に応じて再生成してください。

使用量ダッシュボードがゼロなのに429エラーが発生するのはなぜ？

これは2026年初頭に複数の開発者から報告された「ゴースト429」問題です。Googleのクォータ追跡のサーバー側バグのようです。まず、ダッシュボードで正しいプロジェクトを確認してください。別のクォータを消費する実行中のバッチAPIジョブがないか確認してください。どちらにも該当しない場合、通常15〜30分で自動解消するため待ってください。解消しない場合はGoogle AI Developers Forumで報告してください。

500エラーは自分のせい？Googleのせい？

500 INTERNALエラーはほぼ常にGoogle側の問題ですが、重要な例外があります。入力コンテキストが非常に大きく、モデルのコンテキストウィンドウに近づいているか超えている場合、サーバーが処理に失敗し、より説明的なエラーコードではなく500エラーを返す場合があります。まずGoogle Cloudステータスダッシュボードで既知のインシデントがないか確認してください。サービスは正常だが同じリクエストで一貫して500エラーが発生する場合、入力サイズを減らしてみてください。プロンプトを半分にしてエラーが消えるか確認してください。消えれば境界を見つけたことになります。ランダムなリクエストに影響する散発的な500エラーの場合、指数バックオフのリトライロジックを実装するだけで十分です。Googleのサーバーも分散システムとして一時的な障害を経験し、ほとんどの500エラーは数秒で解消されます。

503 UNAVAILABLEと504 DEADLINE_EXCEEDEDの違いは？

503エラーはGeminiサービスが一時的に過負荷で、現在リクエストを受け付けられないことを意味します。これはGoogle側のキャパシティの問題で、電話回線の話中信号に似ています。通常は数分以内に解消し、ピーク使用期間やGoogleが新しいモデル機能を発表した直後に最も一般的です。一方504エラーは、サーバーがリクエストを受け付けて処理を開始したものの、割り当てられた時間内に完了できなかったことを意味します。これは通常、非常に大きなプロンプトや複雑な推論タスク（特に思考モードのGemini 2.5 Proなど）が原因です。503の場合は30〜60秒待ってリトライしてください。504の場合は大きなリクエストに対してクライアントのタイムアウト設定を少なくとも120秒に増やすか、入力をより小さなチャンクに分割することを検討してください。

APIエラーがユーザーに影響しないようにするには？

最善の戦略は多層防御です。第一に、すべてのリトライ可能なエラーに対して指数バックオフのリトライロジックを実装し、一時的な障害をユーザーから見えなくします。第二に、複数回連続で失敗した後にリクエスト送信を停止するサーキットブレーカーパターンを追加し、カスケード障害を防ぎます。第三に、キャッシュされたレスポンスを返すか、プライマリモデルが利用できない場合に別のモデルに切り替えるフォールバック動作を設定します。第四に、ユーザーが苦情を寄せる前にエラーのスパイクを把握できるよう監視とアラートを設定します。ステータスコード別のエラー率を示す日次メールだけでも、問題の早期発見に役立ちます。本番アプリケーションでは、1つのプロバイダーのレート制限や障害によりアプリケーション全体がダウンしないよう、複数プロバイダーを通じたAPIアクセスの維持を検討してください。

429エラーを多発するとGemini APIからBANされることはある？

Googleはレート制限に達しただけではアカウントをBANしません。429エラーは通常のAPIの使用における想定された動作です。ただし、公開リポジトリで検出されたAPIキーは、セキュリティリスクとしてGoogleが事前にブロックします。APIキーが公開GitHubリポジトリに表示された場合、Googleはそのキーをブロックし、キーが漏洩として報告された旨の特定のエラーメッセージが表示されます。解決策はGoogle AI Studioで新しいAPIキーを生成し、ソースコードにハードコードするのではなく環境変数を使用して安全に保管することです。また、レート制限を回避する目的で複数のGoogle Cloudプロジェクトを作成することはGoogleの利用規約に違反し、アカウントレベルの制限を受ける可能性があります。