エラーコード

エラー形式

すべてのエラーは OpenAI 互換の形式で返ります:

{
  "error": {
    "message": "A human-readable description of the error",
    "type": "error_type",
    "param": "field_name",
    "code": "error_code"
  }
}

param と code フィールドは任意で、null になることがあります。

唯一の例外は POST /v1/messages で、Anthropic の SDK や Claude Code がそのまま解釈できるよう、Anthropic のエンベロープで応答します:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "A human-readable description of the error"
  },
  "request_id": "…"
}

code と param は設定されている場合に error 内に含まれます。モデルのコンテキストウィンドウを超えるリクエストは、メッセージが prompt is too long で始まり capability_rejected: prompt_too_long トークンを含む 400 となります。これは Claude Code の自動圧縮が検出する文言です。以下のステータスコードはどちらの形式にも適用されます。

ステータスコード

ステータス	タイプ	説明
`400`	`invalid_request_error`	リクエスト検証に失敗 — JSON が不正、必須フィールドの欠落、パラメータ値が無効など。
`401`	`authentication_error`	API キーや JWT トークンが欠落しているか無効。
`402`	`billing_error`	課金アカウントの残高が不足しています。クレジットを追加してから再試行してください。
`403`	`authorization_error`	認証情報は有効ですが、対象リソースへの権限が不足しています。
`404`	`invalid_request_error`	リソースが見つかりません — 未知のルート、または参照先のリソース (例: `file_id`) が存在しないか別の組織のものです。
`410`	`invalid_request_error`	リソースが消滅 — 通常は参照されたファイルが `expires_at` を過ぎているケース。
`429`	`rate_limit_error`	レート制限を超過。再試行の方法はバケットによって異なります — レート制限を参照。
`499`	`client_closed_request`	レスポンス完了前にクライアントが切断しました。中断されたストリームで返されます。
`500`	`server_error`	リクエスト処理中に予期せぬエラーが発生しました。
`502`	`server_error`	モデル推論レイヤへの到達に失敗。
`504`	`server_error`	モデルがリクエストタイムアウト内に応答しませんでした。

500、502、504 はいずれも type が "server_error" です。区別するには code を参照してください。500 には code がありません。

主なエラーコード

code フィールドは type よりも具体的な原因を示します。代表的なもの:

コード	ステータス	発生条件
`invalid_value`	400	リクエストフィールドの値が不正 — mime タイプや purpose が不正、`image_url` / `video_url` / `file_id` に必要な capability を選択したモデルが持たない、モデルが対応していないコンテンツパートの種類、対応するツール呼び出しのないツール結果、`tools` にないツールを指定する `tool_choice`、またはモデルのコンテキスト長以上の `max_tokens`（チャットリクエストで `max_completion_tokens` を指定した場合はそのフィールド、`/v1/responses` では `max_output_tokens`）。`param` に該当フィールド名が入ります
`context_length_exceeded`	400	リクエストがモデルの最大コンテキスト長を超過。プロンプトを短くするか、出力トークン数の指定を減らしてください
`unsupported_value`	400	リクエストで使われている `item_reference` などの入力アイテムの種類、またはツールの種類をモデルがサポートしていない。`param` に該当フィールド名が入り、標準的な種類であればメッセージにその名前が含まれます
`file_not_found`	404	指定された `file_id` が存在しないか、組織に紐づいていない
`file_expired`	410	指定された `file_id` が `expires_at` を過ぎている
`invalid_api_key`	401	API キーが欠落、形式不正、または未知
`rate_limit_exceeded`	429	1 分あたり / 1 日あたりのリクエストまたはトークン上限に到達
`insufficient_credits`	402	残高不足
`upstream_error`	502	モデル推論レイヤに到達できない、または応答を読み取れない
`timeout`	504	モデルがリクエストタイムアウト内に応答しなかった
`client_closed_request`	499	レスポンス完了前にクライアントが切断した

エラーハンドリング

from openai import OpenAI, APIError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiand.com/v1",
)

try:
    response = client.chat.completions.create(
        model="deepseek-ai/deepseek-v4-flash",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIError as e:
    print(f"Status: {e.status_code}")
    print(f"Message: {e.message}")

OpenAI SDK はエラーレスポンスを自動的にパースし、型付きの例外を送出します。429 エラーでは X-RateLimit-Policy ヘッダを確認し、バケットに応じて対処してください — 時間ベースの拒否では (Retry-After に従って) バックオフし、concurrency の拒否では再試行せず実行中リクエストを消化させます。レート制限を参照。