ToRouterドキュメントトラブルシューティング
よくある HTTP エラー
ToRouter が返す 400 / 401 / 403 / 404 / 429 / 5xx レスポンスのクイックリファレンスと対処法。
ToRouter は標準的な HTTP セマンティクスに従います。ステータスコードを見れば、問題がリクエスト側、キー側、クォータ側、上流プロバイダ側のどこにあるかが分かります。
| ステータス | ToRouter における意味 | 想定される対処 |
|---|---|---|
| 400 | ボディが不正、model 名が無効、選択したモデルでサポートされないパラメータ | JSON を検証する。/models でモデル slug を確認する。サポートされないフィールドを削る |
| 401 | API キーの欠落・形式不正・未登録（API_KEY_REQUIRED、INVALID_API_KEY、API_KEY_DISABLED、USER_INACTIVE） | Authorization: Bearer sk-*** ヘッダーを確認し、キーが有効化されているか確かめる |
| 402 | アカウント残高不足（従量課金） | Billing → Top up でチャージする |
| 403 | アクセス拒否（IP ホワイトリストによる ACCESS_DENIED）、API_KEY_EXPIRED、SUBSCRIPTION_NOT_FOUND、INSUFFICIENT_BALANCE、モデルがキーのホワイトリストにない | キーの IP ホワイトリスト / モデルホワイトリストを調整、更新、または該当グループへ加入する |
| 404 | サブスクリプション中のグループのカタログにモデルがない、もしくはエンドポイントパスが不明 | /models でグループが公開しているものを確認し、パスがプロトコル（OpenAI / Anthropic / Gemini）と一致するか検証する |
| 429 | レートリミット超過（rate limit exceeded）、API_KEY_QUOTA_EXHAUSTED、または日次/週次/月次サブスクリプションウィンドウ上限 | レートリミット超過 を参照 |
| 500 | ToRouter 内部エラー — バックオフ付きで再試行 | リトライ。継続する場合は x-request-id レスポンスヘッダーを添えて報告する |
| 502 | フェイルオーバー試行後、すべての上流候補が失敗 | アップストリームエラーとフェイルオーバー を参照 |
| 503 | 一時的にサービス利用不可 — 現時点で利用可能なチャネルなし | リトライ。/dashboard でチャネルの健全性を確認 |
| 504 | アップストリームのタイムアウト | リトライ。より小さなモデルや短いプロンプトを検討 |
レスポンスの形
ToRouter はエラーを JSON で返し、少なくとも error フィールドを含みます。正確な形は呼び出したプロトコル（OpenAI / Anthropic / Gemini）に従い、内部に ToRouter 固有のコードが入ります。
{
"error": {
"message": "API key 已过期",
"type": "API_KEY_EXPIRED",
"code": "API_KEY_EXPIRED"
}
}x-request-id レスポンスヘッダーは常にログに記録してください。サポートがリクエストの正確なゲートウェイ経路を追跡するために使用します。