トラブルシューティング ガイド

このガイドでは、Gemini API の呼び出し時に発生する一般的な問題の診断と解決に役立つ情報を説明します。Gemini API バックエンド サービスまたはクライアント SDK のいずれかで問題が発生する可能性があります。クライアント SDK は、次のリポジトリでオープンソース化されています。

API キーに関する問題が発生した場合は、API キーの設定ガイドに沿って API キーが正しく設定されていることを確認してください。

Gemini API バックエンド サービスのエラーコード

次の表に、発生する可能性のある一般的なバックエンド エラーコードと、その原因とトラブルシューティングの手順を示します。

HTTP コード ステータス 説明 例 ソリューション
400 INVALID_ARGUMENT リクエストの本文の形式が正しくありません。 リクエストに誤字脱字があるか、必須フィールドがありません。 リクエストの形式、例、サポートされているバージョンについては、API リファレンスをご覧ください。古いエンドポイントで新しい API バージョンの機能を使用すると、エラーが発生する可能性があります。
400 FAILED_PRECONDITION お住まいの国では Gemini API の無料枠をご利用いただけません。Google AI Studio でプロジェクトの課金を有効にしてください。 無料枠がサポートされていないリージョンでリクエストを行っています。また、Google AI Studio でプロジェクトの課金を有効にしていません。 Gemini API を使用するには、Google AI Studio で有料プランを設定する必要があります。
403 PERMISSION_DENIED API キーに必要な権限がありません。 間違った API キーを使用しています。 適切な認証を行わずにチューニング済みモデルを使用しようとしています。 API キーが設定されていて、適切なアクセス権があることを確認します。チューニング済みモデルを使用するには、適切な認証を行う必要があります。
404 NOT_FOUND リクエストされたリソースが見つかりませんでした。 リクエストで参照されている画像、音声、動画ファイルが見つかりませんでした。 リクエスト内のすべてのパラメータが API バージョンで有効であることを確認します。
429 RESOURCE_EXHAUSTED レート制限を超えています。 無料枠の Gemini API で 1 分あたりのリクエスト数が多すぎます。 モデルのレート制限内であることを確認します。必要に応じて、割り当ての増加をリクエストします。
500 INTERNAL Google 側で予期しないエラーが発生しました。 入力コンテキストが長すぎます。 入力コンテキストを減らすか、別のモデルに一時的に切り替えて（Gemini 2.5 Pro から Gemini 2.5 Flash など）、動作するかどうかを確認します。しばらく待ってからリクエストを再試行してください。再試行しても問題が解決しない場合は、Google AI Studio の [フィードバックを送信] ボタンを使用して報告してください。
503 UNAVAILABLE サービスが一時的に過負荷状態になっているか、ダウンしている可能性があります。 サービスの一時的な容量不足です。 別のモデルに一時的に切り替えて（Gemini 2.5 Pro から Gemini 2.5 Flash など）、動作するかどうかを確認します。しばらく待ってからリクエストを再試行してください。再試行しても問題が解決しない場合は、Google AI Studio の [フィードバックを送信] ボタンを使用して報告してください。
504 DEADLINE_EXCEEDED サービスが期限内に処理を完了できません。 プロンプト（またはコンテキスト）が大きすぎて、時間内に処理できません。 このエラーを回避するには、クライアント リクエストで「タイムアウト」を大きく設定します。

API 呼び出しでモデル パラメータのエラーを確認する

モデル パラメータが次の値の範囲内であることを確認します。

モデル パラメータ 値（範囲）
候補数 1 ～ 8（整数）
温度 0.0 ～ 1.0
最大出力トークン 使用しているモデルの最大トークン数をモデルページ で確認します。
TopP 0.0 ～ 1.0

パラメータ値を確認するだけでなく、必要な機能をサポートする正しい API バージョン（例: /v1 や /v1beta）と モデルを使用していることを確認してください。たとえば、機能がベータ版リリースの場合、/v1beta API バージョンでのみ使用できます。

適切なモデルを使用していることを確認する

モデルページ に記載されているサポート対象モデルを使用していることを確認します。

2.5 モデルでのレイテンシの増加またはトークン使用量の増加

2.5 Flash モデルと Pro モデルでレイテンシの増加やトークン使用量の増加が見られる場合は、品質向上のために思考がデフォルトで有効になっている ことが原因である可能性があります。速度を優先する場合や、費用を最小限に抑える必要がある場合は、思考を調整または無効にできます。

ガイダンスとサンプルコードについては、思考ページを ご覧ください。

安全性に関する問題

API 呼び出しで安全設定が原因でプロンプトがブロックされた場合は、API 呼び出しで設定したフィルタに関してプロンプトを確認してください。

BlockedReason.OTHER が表示された場合、クエリまたはレスポンスが 利用規約 に違反しているか、サポートされていない可能性があります。

暗唱の問題

RECITATION という理由でモデルの出力生成が停止した場合は、モデル出力が特定のデータに似ている可能性があります。この問題を解決するには、プロンプト / コンテキストをできるだけ一意にし、Temperature を高くしてみてください。

トークンの繰り返しに関する問題

出力トークンが繰り返される場合は、次の方法を試して、トークンを減らすか削除してください。

説明 原因 推奨される回避策
Markdown テーブルでハイフンが繰り返される モデルが視覚的に整列された Markdown テーブルを作成しようとすると、テーブルの内容が長くなる場合に発生することがあります。ただし、正しいレンダリングには Markdown の配置は必要ありません。

プロンプトに手順を追加して、Markdown テーブルを生成するための具体的なガイドラインをモデルに提供します。 ガイドラインに沿った例を示します。温度を調整してみることもできます。コードや Markdown テーブルなどの非常に構造化された出力を生成する場合、Temperature（>= 0.8）の方が効果的であることがわかっています。

この問題を回避するためにプロンプトに追加できるガイドラインの例を次に示します。 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Markdown テーブルでトークンが繰り返される ハイフンの繰り返しと同様に、モデルがテーブルの内容を 視覚的に整列しようとすると発生します。正しいレンダリングには Markdown の配置は 必要ありません。
  • 次のような手順をシステム プロンプトに追加してみてください。 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • 温度を調整してみてください。一般に、温度を高くする（>= 0.8） 出力の繰り返しや重複を解消できます。
構造化出力で改行（\n）が繰り返される モデルの入力に Unicode や \u、\t などのエスケープ シーケンスが含まれていると、改行が繰り返されることがあります。
  • プロンプトで禁止されているエスケープ シーケンスを確認し、UTF-8 文字に置き換えます。 たとえば、JSON の例で \u エスケープ シーケンスを使用すると、モデルがそのエスケープ シーケンスを出力で使用する可能性があります。
  • 許可されているエスケープについてモデルに指示します。次のようなシステム指示を追加します。 これ: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
構造化出力を使用してテキストが繰り返される モデル出力で、フィールドの順序が定義された構造化スキーマと異なる場合、テキストが繰り返されることがあります。
  • プロンプトでフィールドの順序を指定しないでください。
  • すべての出力フィールドを必須にします。
ツール呼び出しの繰り返し モデルが以前の思考のコンテキストを失った場合や、強制的に使用できないエンドポイントを呼び出した場合に発生することがあります。 思考プロセス内で状態を維持するようにモデルに指示します。 システム指示の末尾に以下を追加します。 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
構造化出力の一部ではないテキストの繰り返し モデルが解決できないリクエストでスタックした場合に発生することがあります。
  • 思考がオンになっている場合は、手順で問題の解決方法を 明示的に指示しないでください。最終的な 出力のみをリクエストします。
  • Temperature を 0.8 以上にしてみてください。
  • 「簡潔に」、「繰り返さない」、または 「回答は 1 回のみ」などの手順を追加します。

ブロックされた API キーまたは機能しない API キー

このセクションでは、Gemini API キーがブロックされているかどうかを確認する方法と、その対処方法について説明します。

キーがブロックされる理由を理解する

一部の API キーが公開されている可能性がある脆弱性が特定されました。データを保護し、不正アクセスを防ぐため、既知の漏洩したキーが Gemini API にアクセスできないように事前にブロックしました。

キーが影響を受けているかどうかを確認する

キーが漏洩していることが判明した場合、Gemini API でそのキーを使用することはできません。Google AI Studio を使用すると、Gem101}ini API の呼び出しがブロックされている API キーを確認し、新しい キーを生成できます。これらのキーを使用しようとすると、次のエラーが返されることもあります。

Your API key was reported as leaked. Please use another API key.

ブロックされた API キーに対するアクション

Google AI Studio を使用して、Gemini API 統合用の新しい API キーを生成する必要があります。新しいキーが安全に保たれ、公開されないように、API キーの管理方法を見直すことを強くおすすめします。

脆弱性による予期しない請求

課金サポートケースを送信してください。 課金チームが対応を進めており、最新情報をできるだけ早くお知らせいたします。

漏洩したキーに対する Google のセキュリティ対策

API キーが漏洩した場合、Google はアカウントの費用超過や不正使用を防ぐためにどのような対策を講じますか？

モデル出力を改善する

モデルの出力の品質を高めるには、より構造化されたプロンプトを作成してみてください。プロンプト エンジニアリング ガイドのページでは、基本的なコンセプト、戦略、ベスト プラクティスについて説明しています。

トークン上限について

トークン ガイドを読んで、トークンのカウント方法と上限について理解を深めてください。

既知の問題

  • この API は、一部の言語のみをサポートしています。サポートされていない言語でプロンプトを送信すると、予期しないレスポンスやブロックされたレスポンスが生成される可能性があります。最新情報については、 対応言語をご覧ください。

バグを報告する

ご不明な点がありましたら、 Google AI デベロッパー フォーラム のディスカッションにご参加ください。