AI API エラーレスポンス

LLMPool の OpenAI 互換 API と Anthropic 互換 API は、それぞれのプロトコルに対応したエラー形式を使用します。アプリケーションは最初に HTTP ステータスを確認し、次に構造化されたエラーフィールドを読み取ってください。

エラーメッセージは人が読むためのもので、安定した解析契約ではありません。message の文字列を照合して再試行や処理分岐を決めないでください。

OpenAI 互換形式

{
  "error": {
    "message": "The requested model was not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

フィールド	型	説明
`error.message`	string	開発者向けの安全な説明
`error.type`	string	OpenAI 互換エラー分類
`error.param`	string または null	関連するリクエストフィールド
`error.code`	string または null	プログラムで判定できるエラーコード

HTTP ステータスと error.code を優先して処理してください。

Anthropic 互換形式

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested model was not found."
  }
}

フィールド	型	説明
`type`	string	常に `error`
`error.type`	string	Anthropic 互換エラー分類
`error.message`	string	開発者向けの安全な説明
`error.code`	string または省略	`ip_not_allowed` など一部のエラーのみ

Anthropic クライアントは HTTP ステータスと error.type を主に使用してください。

フィールドの定義元

内容	主な定義元	クライアントでの扱い
HTTP ステータス	LLMPool が障害分類に基づき標準化。一部の透過レスポンスは上流値を保持	下表の分類に従う
OpenAI `error.code`	LLMPool が定義する一般的なコード	HTTP ステータスと組み合わせて判定可能
OpenAI `error.type` / Anthropic `error.type`	LLMPool が互換形式へ変換。透過レスポンスでは上流由来の場合あり	文書化された型のみを使用
`error.message`	安全な標準文、または透過された上流文	表示、ログ、手動調査にのみ使用

非 2xx の正常な業務レスポンス

一部の互換上流は、構造が正しい業務レスポンスに非 2xx ステータスを付けることがあります。LLMPool は内容が対象エンドポイントと一致すると確認できた場合、ステータスを保持したまま業務オブジェクトを返すことがあります。

Chat Completions と Responses の有効な OpenAI オブジェクト
Anthropic の非ストリーミング Messages、Files、Message Batches オブジェクト
status: "failed" と使用量を含む Responses オブジェクト

非 2xx を受けたクライアントは、エラー envelope を読む前に対象エンドポイントの業務オブジェクトか確認してください。

主な HTTP ステータス

ステータス	意味	推奨対応
`400`	リクエスト、パラメーター、モデル機能、コンテキスト長が不正	修正して再送信
`401`	API キーが無効	キーと認証 Header を確認。自動再試行しない
`402`	アカウント残高不足	入金後に再送信
`403`	送信元 IP が許可されていない	IP 許可リストを確認
`404`	モデル、レスポンス、リソースが存在しない	ID とパスを確認
`405`	HTTP メソッドが未対応	文書化されたメソッドを使用
`413`	リクエストが大きすぎる	本文または添付を縮小
`422`	JSON は有効だがパラメーターの組み合わせが不正	修正して再送信
`429`	プラットフォームまたは上流のレート制限	`Retry-After` に従いバックオフ
`500`	LLMPool 内部エラー。Anthropic では上流設定エラーの場合あり	構造化された型で判断
`502`	上流設定エラーまたは上流が利用不能	`error.code` で再試行可否を判断
`503`	OpenAI 互換モデルの容量なし	バックオフまたはモデル変更
`504`	上流タイムアウト	バックオフし、必要なら入力を短縮
`529`	Anthropic 互換上流またはモデルの過負荷	バックオフまたはモデル変更

詳しくはトラブルシューティングを参照してください。

ストリーミングエラー

HTTP 200 とレスポンス Header の送信後にストリームが失敗する場合があります。クライアントは最初の HTTP ステータスだけでなく SSE イベントを最後まで解析する必要があります。

Chat Completions

{
  "error": {
    "message": "Upstream stream interrupted.",
    "type": "server_error",
    "param": null,
    "code": "stream_error"
  }
}

Responses API

{
  "type": "error",
  "code": "stream_error",
  "message": "Upstream stream interrupted.",
  "param": null,
  "sequence_number": 7
}

Responses API は正規の response.failed 終端イベントを返すこともあります。

{
  "type": "response.failed",
  "sequence_number": 7,
  "response": {
    "id": "resp_123",
    "object": "response",
    "status": "failed",
    "error": {
      "code": "server_error",
      "message": "The response failed."
    }
  }
}

response.failed は Responses プロトコルの業務終端です。LLMPool はこのイベントを転送してストリームを終了し、合成エラーを追加しません。type: "error" と type: "response.failed" の両方を処理してください。

Anthropic Messages

Anthropic Messages は SSE event: error を使用します。

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Upstream stream interrupted."
  }
}

ストリームエラーや失敗終端を受信したらストリームを終了し、受信済み断片を完全なレスポンスとして扱わないでください。

再試行の原則

400、401、402、403、404、405、413、422 は、通常リクエストやアカウント状態の修正が必要です。
429 rate_limit_exceeded、429 rate_limited、502 upstream_unavailable、503 service_unavailable、504 upstream_timeout、529 overloaded_error はジッター付き指数バックオフを使用できます。
502 upstream_configuration_error と 400/500 meter_price_rules_error はプラットフォーム設定の問題で、同じ内容の再試行は通常無効です。
500 internal_error または Anthropic 500 api_error は少数回のみ再試行し、継続する場合はサポートへ連絡してください。
Retry-After Header を優先してください。
リソース作成や Batch など非冪等操作は、最初のリクエストが成功していないことを確認してから再試行してください。
最大回数と総タイムアウトを必ず設定してください。

LLMPool は標準エラーに上流の生レスポンス、認証情報、内部モデル名、API Base、プロキシ URL を含めません。サポートへ連絡する際も API キー、リクエスト本文、ファイル内容を送信しないでください。