API エラー

このページでは、すべての Interactions API エラーコードのリファレンス、エラーレスポンスの形式、API がさまざまなリクエストタイプのエラーを返す方法について説明します。

標準 API エラーコード

これらの一般的なリクエストレベルのエラーコードは、標準の HTTP ステータスコードに対応しています。アプリケーションロジックで code フィールドを使用して、エラーをプログラムで処理します。

コード	HTTP ステータス	説明	推奨される対処方法
`invalid_request`	400 無効なリクエスト	リクエストペイロードの形式が正しくないか、無効なパラメータが含まれています。	API リファレンスでリクエストの構文とパラメータを確認します。
`failed_precondition`	400 無効なリクエスト	前提条件が満たされていないため（課金が無効になっているなど）、リクエストを処理できません。	プロジェクトの課金ステータスまたはアカウントの前提条件を確認します。
`out_of_range`	416 Requested Range Not Satisfiable	リクエストパラメータが有効な範囲外です。	パラメータ値と上限を確認します。
`parameter_unknown`	400 無効なリクエスト	リクエストに不明なパラメータが含まれている。	認識されないパラメータを削除して、もう一度お試しください。
`authentication`	401 未認証	API キーがない、無効である、または期限が切れている。	API キーを確認します。
`payment_required`	402 Payment Required	前払いクレジット残高が不足しています。	請求先アカウントにクレジットを追加するか、オートチャージをオンにしてください。再試行しないでください。クレジットが追加されるまでリクエストは成功しません。
`permission_denied`	403 禁止	API キーにこのリソースに対する権限がないか、プロジェクトの API アクセスが制限されています。	API キーの権限、プロジェクトティアの利用資格、お支払いステータスを確認してください。プロジェクトが制限されている、または利用できない場合のトラブルシューティングをご覧ください。
`not_found`	404 見つかりません	リクエストされたリソースが見つかりませんでした。	リソースパスとパラメータを確認してください。
`model_not_found`	404 見つかりません	指定されたモデルが見つかりませんでした。	モデル名を確認するか、別のモデルにフォールバックしてください。
`already_exists`	409 競合しています。	作成しようとしたエンティティはすでに存在します。	再作成する前に、リソースがすでに存在するかどうかを確認します。
`aborted`	409 競合しています。	競合または同時実行チェックの失敗により、オペレーションが中止されました。	より高いアプリケーションレベルでリクエストを再試行します。
`rate_limit_exceeded`	429 Too Many Requests（リクエスト数が多すぎる）	1 分あたりまたは 1 秒あたりのリクエスト数またはトークン数の上限を超えています。	指数バックオフを利用して、待機と再試行を繰り返してください。
`quota_exceeded`	429 Too Many Requests（リクエスト数が多すぎる）	1 日の割り当てを超過しました。	割り当てがリセットされるまで待つか、割り当ての増加をリクエストします。
`too_many_requests`	429 Too Many Requests（リクエスト数が多すぎる）	短期間にリクエストが集中しています。	指数バックオフを利用して、待機と再試行を繰り返してください。
`cancelled`	499 Client Closed Request	クライアントが完了前にリクエストをキャンセルしました。	特に対応は必要ありません。通常、これはクライアントが切断されたことを意味します。
`api_error`	500 Internal Server Error（内部サーバーエラー）	サーバーで予期しないエラーが発生しました。	リクエストを再試行します。問題が解決しない場合は、サポートにお問い合わせください。
`unimplemented`	501 Not Implemented	オペレーションまたは機能が実装されていないか、サポートされていません。	API の機能を確認するか、サポートされている機能に切り替えてください。
`service_unavailable`	503 Service Unavailable（サービス利用不可）	サービスが一時的に過負荷状態になっているか、停止しています。	指数バックオフを利用して、待機と再試行を繰り返してください。
`deadline_exceeded`	504 Gateway Timeout（ゲートウェイタイムアウト）	期限内にリクエストが完了しませんでした。	クライアントの期限設定を削除するか、期限を延長して、サーバーのデフォルトを使用します。

生成がブロックされたコード

これらのエラーコードは、ポリシー、安全性、またはコンテンツの制限によりモデルの出力がブロックされたことを示します。これらのコードのいずれかを受け取った場合は、入力を変更して再試行してください。

コード	説明
`safety`	安全性違反（有害なコンテンツ）によりリクエストがブロックされました。
`recitation`	著作権または朗読の制限により、リクエストがブロックされました。
`language`	サポートされていない言語によりリクエストがブロックされました。
`prohibited_content`	禁止コンテンツのガイドラインによりリクエストがブロックされました。
`spii`	個人を特定できる機密情報の制限により、リクエストがブロックされました。
`blocklist`	ブロックリストの禁止用語によりリクエストがブロックされました。
`image_safety`	安全性の違反により、画像生成がブロックされました。
`image_prohibited_content`	禁止コンテンツのガイドラインにより、画像の生成がブロックされました。
`image_recitation`	著作権または引用の制限により、画像生成がブロックされました。
`image_other`	不明な理由により画像生成がブロックされました。
`content_blocked`	不明なポリシー上の理由により、リクエストがブロックされました。

生成エラーコード

これらのエラーコードは、モデルの生成された出力に構造上の問題（不正な形式の関数呼び出しや宣言されていないツール呼び出しなど）があることを示します。

コード	説明
`malformed_function_call`	モデルが、解析できない関数呼び出しを生成しました。
`malformed_tool_call`	モデルが、解析できないツール呼び出しを生成しました。
`unexpected_tool_call`	モデルが、リクエストで宣言されていないツールを呼び出しました。
`no_image`	モデルが画像を生成できませんでした。
`too_many_tool_calls`	モデルが、許可されている数を超えるツール呼び出しを生成しました。
`missing_thought_signature`	レスポンスに必須の思考シグネチャがありません。

エラーレスポンスの形式

Interactions API からのエラーはすべて、code と message を含む error オブジェクトを返します。たとえば、サポートされていないツールタイプを渡すと、次のように返されます。

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}

フィールド	タイプ	説明
`code`	文字列	`snake_case` の機械で読み取り可能なエラーコード。
`message`	文字列	発生した問題に関する、人間が読んで理解できる説明。

エラーの配信方法

API は、標準の HTTP リクエストとストリーミング（SSE）リクエストのどちらを行うかによって、エラーの配信方法が異なります。

標準 HTTP リクエスト

標準（非ストリーミング）リクエストの場合、API は HTTP レスポンスステータスコード（400 Bad Request、401 Unauthorized、429 Too Many Requests など）を設定し、JSON レスポンス本文で error オブジェクトを返します。

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

ストリーミング（SSE）リクエスト

ストリーミングリクエスト（stream: true）の場合、API は event_type を "error" に設定して、サーバー送信イベント（SSE）ストリームを介してエラーイベントを送信します。error フィールドには、同じ code 構造と message 構造が含まれています。

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

SSE イベントスキーマの詳細については、Interactions API リファレンスをご覧ください。

次のステップ

API のトラブルシューティング: 一般的な問題とエラーのシナリオを解決します。
レート制限: リクエストの上限と割り当ての処理について説明します。