API エラー

このページでは、GenerateContent API から返されるバックエンド エラーコードのリファレンス、gRPC エラー レスポンスの形式、トラブルシューティングの手順について説明します。

HTTP エラーコード

次の表に、一般的なバックエンド エラーコード、その原因の説明、推奨される解決策を示します。

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 API のレート上限（RPM、TPM、RPD、費用など）のいずれかを超えています。 リクエストの送信数が多すぎる、トークンの使用数が多すぎる、アカウントのお支払い履歴と階層に基づく上限を超えている。 モデルのレート上限を超えていないことを確認します。しばらく待ってから再試行してください。リクエストのレートまたはサイズを減らします。必要に応じて、レート上限の引き上げをリクエストします。
499 CANCELLED オペレーションがキャンセルされました。通常、キャンセルは呼び出し元により行われます。 API がレスポンスを完了する前に、クライアントが接続を閉じました。 クライアントまたはネットワーク インフラストラクチャが接続を早期に終了しているかどうかを確認します（クライアントサイドのタイムアウトなど）。
500 INTERNAL Google 側で予期しないエラーが発生しました。 入力コンテキストが長すぎます。 Gemini API のステータス ページで、進行中のインシデントがないか確認します。入力コンテキストを減らすか、別のモデルに一時的に切り替えて（Gemini 2.5 Pro から Gemini 2.5 Flash など）、動作するかどうかを確認します。しばらく待ってから、もう一度リクエストしてみてください。再試行しても問題が解決しない場合は、Google AI Studio の [フィードバックを送信] ボタンを使用してご報告ください。
503 UNAVAILABLE サービスが一時的に過負荷状態になっているか、ダウンしている可能性があります。 サービスが一時的に容量不足になっています。 Gemini API のステータス ページで、進行中のインシデントがないか確認します。別のモデルに一時的に切り替えて（Gemini 2.5 Pro から Gemini 2.5 Flash など）、動作するかどうかを確認します。しばらく待ってから、もう一度リクエストしてみてください。再試行しても問題が解決しない場合は、Google AI Studio の [フィードバックを送信] ボタンを使用してご報告ください。
504 DEADLINE_EXCEEDED サービスが期限内に処理を完了できません。 プロンプト（またはコンテキスト）が大きすぎて、時間内に処理できません。 このエラーを回避するには、クライアント リクエストで「タイムアウト」を大きく設定します。

エラー レスポンスの形式

GenerateContent リクエストが失敗すると、API は HTTP ステータス コード（400 Bad Request、403 Forbidden、429 Too Many Requests など）を設定し、gRPC ステータスの詳細を含む JSON レスポンス本文を返します。

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
フィールド タイプ 説明
code integer HTTP ステータス コード。
message 文字列 エラーの説明（人が読める形式）。
status 文字列 SCREAMING_CASE の gRPC ステータス コード。
details 配列 ErrorInfo や LocalizedMessage などのエラーに関する追加のコンテキスト。

次のステップ