エラー · Tokener

モデル API のすべてのレスポンス（成功・エラーいずれも）には x-request-id と request-id レスポンスヘッダー（req_<32桁の16進文字>）が付与されます。サポートへ連絡する際はこの値を添えてください。

非ストリーミングのエラー

エラー時は非 2xx の HTTP ステータスと JSON ボディが返ります。形状はリクエストのプロトコルに従います。

OpenAI 形式のパス（/models、/chat/completions、/embeddings、 /responses）：

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic 形式のパス（/messages）：

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

ストリーミングのエラー

stream: true でストリーム開始後にエラーが発生した場合、HTTP エラースタタスではなく 1 つの SSE フレームとしてエラーが届きます。パスにより 3 種類の形状があります。

/chat/completions（OpenAI Chat Completions）：

data: {"error":{"message":"Upstream request failed.","type":"upstream_error","param":null,"code":"provider_error"}}

/messages（Anthropic Messages）：

event: error
data: {"type":"error","error":{"type":"api_error","message":"Upstream request failed."},"request_id":"req_1f2e3d4c5b6a7988a1b2c3d4e5f60718"}

/responses（OpenAI Responses）：

event: error
data: {"type":"error","code":"provider_error","message":"Upstream request failed.","param":null}

エラーコード

code（OpenAI 形式）と error.type（Anthropic 形式）は安定しており、分岐条件として安全に使えます。message の文言は安定しておらず、予告なく変わり得ます。

HTTP ステータス	`code`	OpenAI `type`	Anthropic `type`	意味
400	`invalid_request`	`invalid_request_error`	`invalid_request_error`	リクエストが不正
401	`invalid_api_key`	`authentication_error`	`authentication_error`	API キーが未設定または無効
402	`insufficient_credits`	`billing_error`	`billing_error`	プリペイド残高が不足
403	`permission_denied`	`permission_error`	`permission_error`	キーがこのモデル/パスにアクセス権を持たない
404	`route_not_found`	`invalid_request_error`	`not_found_error`	未知のパス
404	`model_not_found`	`invalid_request_error`	`not_found_error`	モデル id が存在しない
405	`method_not_allowed`	`invalid_request_error`	`invalid_request_error`	そのパスに対して不正な HTTP メソッド
413	`request_too_large`	`invalid_request_error`	`request_too_large`	リクエストボディがサイズ上限を超過
429	`rate_limit_exceeded`	`rate_limit_error`	`rate_limit_error`	リクエストが多すぎる（`retry-after` ヘッダーを参照）
502	`provider_error`	`upstream_error`	`api_error`	アップストリームのプロバイダー呼び出しが失敗
503	`overloaded`	`service_unavailable_error`	`overloaded_error`	Gateway の同時処理上限に到達。後で再試行
503	`gateway_unavailable`	`service_unavailable_error`	`api_error`	アップストリームに到達できない
504	`upstream_timeout`	`timeout_error`	`api_error`	アップストリームの応答がタイムアウト

SDK での実装アドバイス

message ではなく code / error.type と HTTP ステータスで分岐してください。4xx は基本的にリトライ対象外（429 は retry-after 後にリトライ可）とし、5xx（502/503/504）はバックオフ付きでリトライ可能として扱ってください。