ドキュメントAPI リファレンスエラーコード

エラーコード

3 種類のエラーエンベロープ、カテゴリと HTTP ステータスの対応、よくあるエラー一覧。

ゲートウェイは 3 社の API 形式を提供しており、エラーレスポンスも呼び出した API の形式に一致します。判定はパスによります：/v1/messages* は Anthropic 形式、/v1beta/* は Google 形式、それ以外は OpenAI 形式です。これにより各 SDK のエラー解析がそのまま機能します。

3 種類のエラーエンベロープ

OpenAI

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Anthropic

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Google

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "status": "UNAUTHENTICATED"
  }
}

カテゴリとステータスコードの対応

カテゴリ	HTTP	OpenAI `type`	Anthropic `type`	Google `status`
認証失敗	401	`invalid_request_error`	`authentication_error`	`UNAUTHENTICATED`
権限不足	403	`invalid_request_error`	`permission_error`	`PERMISSION_DENIED`
リソースなし	404	`invalid_request_error`	`not_found_error`	`NOT_FOUND`
未対応エンドポイント	404	`invalid_request_error`	`not_found_error`	`INVALID_ARGUMENT`
不正なリクエスト	400	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
レート制限	429	`rate_limit_error`	`rate_limit_error`	`RESOURCE_EXHAUSTED`
クォータ/残高不足	402	`insufficient_quota`	`billing_error`	`RESOURCE_EXHAUSTED`
ペイロード過大	413	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
上流障害	502	`api_error`	`api_error`	`UNAVAILABLE`
過負荷	503	`server_error`	`overloaded_error`	`UNAVAILABLE`
内部エラー	500	`api_error`	`api_error`	`INTERNAL`

よくあるエラー

メッセージ id	HTTP	意味と対処
`key_missing` / `key_invalid`	401	API キー未指定または無効。認証ヘッダーを確認してください。
`key_disabled` / `key_expired` / `key_ip_denied`	403	キーが無効化/期限切れ、または送信元 IP が許可リスト外です。
`key_quota_exhausted`	402	キーの利用上限に達しました。リセットを待つか上限を変更してください。
`balance_exhausted`	402	アカウント残高が不足しています。チャージ後に再試行してください。
`rpm_exceeded` / `concurrent_exceeded`	429	RPM または同時実行数の上限超過。バックオフして再試行してください。
`model_missing`	400	リクエストに `model` フィールドがありません。
`model_not_found` / `model_disabled`	404	モデルが存在しないか提供終了です。モデル一覧で id を確認してください。
`no_upstream_for_model`	404	このモデルを提供できる供給元が現在ありません。後で再試行するか管理者に連絡してください。
`moderation_blocked`	403	コンテンツ審査で拒否されました。内容を修正して再試行してください。
`body_too_large`	413	リクエストボディがこのエンドポイントの上限を超えています。インラインメディアを圧縮するか別のエンドポイントを使ってください。
`upstream_timeout` / `upstream_unreachable` / `all_upstreams_down`	502	上流のタイムアウト/接続不可/全遮断です。バックオフして再試行してください。
`server_busy`	503	ゲートウェイの同時処理容量が満杯です。しばらくして再試行してください。
`balance_insufficient`	402	残高から処理中リクエストの見積額を引くと今回の費用に足りません（アカウント残高参照）。チャージするか処理中リクエストの完了を待ってください。
`entry_unsupported`	404	そのパス/メソッドはゲートウェイが対応するエンドポイントではありません。
`model_rejects_format` / `no_endpoint_for_format`	404	モデルがこのエンドポイントのプロトコルを受け付けないか、そのプロトコルを扱える供給元がありません。モデル本来のエンドポイント（GPT 系は Responses、Claude 系は Messages など）を使ってください。
`model_not_schedulable` / `no_group_available`	404 / 403	モデルがスケジュール可能な範囲外か、利用できるスケジューリンググループがありません。管理者に連絡してください。
`client_not_allowed`	403	このクライアントはどのグループも利用できません。自作・未登録のクライアントは管理者に登録を依頼してください。
`account_disabled` / `account_deleted`	403	キーの所属アカウントが停止または退会済みです。
`privacy_filter_failed`	500	プライバシーフィルターの実行に失敗しリクエストを拒否しました。管理者にフィルタールールの確認を依頼してください。
`video_job_missing` / `video_job_not_found` / `video_job_route_gone`	400 / 404 / 502	動画のポーリングでジョブ id がない、ジョブが存在しない、またはジョブの供給元が削除済みです（画像と動画参照）。

エラーメッセージはアカウントの言語設定（認証前は Accept-Language、既定は英語）にローカライズされます。プログラムでは HTTP ステータスと type/status フィールドで分岐し、message テキストを照合しないでください。

リトライとバックオフの具体的な方法はエラー処理とリトライを参照してください。