エラーコード

エラー形式

すべてのエラーは 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 に該当フィールド名が入ります
invalid_media_url	400	メディア URL が URL の要件 を満たしていない。例: http の URL、IP アドレス、内部ホスト名。公開 https URL、file_id、base64 の data: URL のいずれかを使ってください。param に該当フィールド名が入ります
context_length_exceeded	400	リクエストがモデルの最大コンテキスト長を超過。プロンプトを短くするか、出力トークン数の指定を減らしてください
unsupported_value	400	利用できない機能をリクエストが使っている。/v1/responses での previous_response_id や item_reference 入力アイテム（レスポンスオブジェクトは保存されません）、またはモデルがサポートしていない入力アイテムの種類やツールの種類。param に該当フィールド名が入り、標準的な種類であればメッセージにその名前が含まれます
file_not_found	404	指定された file_id が存在しないか、組織に紐づいていない
file_expired	410	指定された file_id が expires_at を過ぎている
endpoint_removed	410	/v1/completions など、廃止されたエンドポイントへのリクエスト。メッセージに代わりのエンドポイントが示されます
model_not_found	404	model が正確なモデル id ではない、またはモデルに組織の請求通貨での価格が設定されていない。チャットモデルは GET /v1/models、動画モデルは GET /v1/videos/models で確認できます
model_deprecated	404	モデルは提供を終了した。代わりに使うモデルをメッセージで案内する
model_access_denied	404	モデルは存在するが、組織にそのモデルの利用権限がない。利用を希望する場合は support@aiand.com までお問い合わせください
invalid_api_key	401	API キーが欠落、形式不正、または未知
rate_limit_exceeded	429	レート制限を超過。モデルバケットによる拒否では X-RateLimit-Policy、認証スロットルでは Retry-After のみが付く
insufficient_credits	402	残高不足
upstream_error	502	モデル推論レイヤに到達できない、または応答を読み取れない
timeout	504	モデルがリクエストタイムアウト内に応答しなかった
client_closed_request	499	レスポンス完了前にクライアントが切断した

reasoning をオフにする

モデルが reasoning をオフにできるのは、公開しているレベルに none が含まれる場合だけです。none を公開していない推論モデルへ reasoning_effort の none、reasoning.effort の none、または /v1/messages の thinking ブロックで type disabled を送ると、400 invalid_request_error になります。

Model '<name>' cannot disable reasoning: suppressing it needs reasoning_effort 'none', which this model does not publish. Supported values: <levels>. Use '<level>' for the least reasoning.

<level> は、そのモデルが公開しているレベルのうち最も低いものです。reasoning 機能を持たないモデルは、これらのフィールドを無視します。

その他の reasoning レベルのエラー

none 以外でモデルの一覧にないレベルは、失敗せず一つ上のレベル(なければ最も高いレベル)で実行されます。一覧にない none は上記の 400 になります。ultra のように effort の語彙にない値は Model '<name>' does not support <field> '<value>'. Supported values: <levels>. になります。レベルを一つも持たない推論モデルは、どのレベルにも Model '<name>' lists no reasoning levels, so it cannot apply <field>. を返します。

エラーハンドリング

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="google/gemma-4-31b-it",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIError as e:
    print(f"Status: {e.status_code}")
    print(f"Message: {e.message}")

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