ドキュメント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	ゲートウェイの同時処理容量が満杯です。しばらくして再試行してください。

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

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