リファレンス
エラーコード完全リファレンス
ゲートウェイが返すエラータイプと HTTP ステータス、意味、次の一手。
ToRouter のエラー応答にはタイプコード（多くの場合 JSON の type）が含まれます。以下はゲートウェイ自身が返す代表的なタイプです。上流（OpenAI / Anthropic / Gemini）由来のエラーは各社の type とメッセージのまま透過されます — 各プロバイダのドキュメントを参照してください。
| タイプ | ステータス | 意味 | 対処 |
|---|
API_KEY_REQUIRED | 401 | リクエストヘッダに API キーがない | Authorization: Bearer sk-*** を送る |
INVALID_API_KEY | 401 | キーが認識されない | タイポを確認。失効している可能性あり |
API_KEY_DISABLED | 401 | /keys でキーが無効化された | 再有効化または新規作成 |
API_KEY_EXPIRED | 403 | キーの有効期限を過ぎている | 期限を延長またはローテーション |
API_KEY_QUOTA_EXHAUSTED | 429 | キーに設定した支出上限に達した | 上限を引き上げまたはローテーション |
USER_NOT_FOUND | 401 | キーを所有するユーザーが存在しない | サポートに連絡 |
USER_INACTIVE | 401 | 所有ユーザーが停止 / 未検証 | メール検証、アカウント状態確認 |
| タイプ | ステータス | 意味 | 対処 |
|---|
ACCESS_DENIED | 403 | クライアント IP がキーのホワイトリスト外（またはブラックリストに含まれる）、もしくはモデルがホワイトリストにない | キーの IP / モデル制限を更新 |
SUBSCRIPTION_NOT_FOUND | 403 | このキーには有効なサブスクリプションが必要だが未登録 | /subscriptions で加入を完了 |
INSUFFICIENT_BALANCE | 403 | 従量課金のアカウント残高 ≤ 0 | /billing/topup でチャージ |
| タイプ | ステータス | 意味 | 対処 |
|---|
rate limit exceeded（トップレベル error） | 429 | IP 単位 / キー単位のリクエストレートリミット | バックオフ、上限を引き上げ |
USAGE_LIMIT_EXCEEDED | 429 | プランの日次 / 週次 / 月次ウィンドウ上限 | ウィンドウのリセットを待つか、より高い用量のプランへ移行 |
SUBSCRIPTION_INVALID | 403 | サブスクリプションが停止、解約、または無効 | /subscriptions で更新 |
| タイプ | ステータス | 意味 | 対処 |
|---|
api_key_in_query_deprecated | 400 | API キーが ?key= や ?api_key= で渡された（廃止） | キーを Authorization ヘッダーに移す |
invalid_request_error（上流からの透過） | 400 | ボディが上流の検証に失敗 | リクエスト形を修正 |
| タイプ | ステータス | 意味 | 対処 |
|---|
upstream_unavailable | 502 / 503 | 候補チャネルすべてが失敗 | バックオフ付きでリトライ。利用状況ダッシュボード または 利用状況の詳細 を確認 |
upstream_timeout | 504 | 上流が時間内に応答しなかった | リトライ。より小さなモデルや短いプロンプトを試す |
INTERNAL_ERROR | 500 | 予期しないゲートウェイエラー | リトライ。継続する場合は x-request-id を添えて報告 |
プロトコル（OpenAI / Anthropic / Gemini）ごとに応答の形は少し異なりますが、同じ type の意味は共通です。
{
"error": {
"type": "API_KEY_EXPIRED",
"code": "API_KEY_EXPIRED",
"message": "API key 已过期"
}
}
type / code：上の表と照合。message：人間向けの説明。レガシーコードでは中国語の場合あり。- レスポンスヘッダー
x-request-id：問題報告時に添付。
ToRouterドキュメント