錯誤碼

WRouter 錯誤響應統一為：

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

HTTP 狀態碼與 OpenAI 一致。

HTTP 狀態碼

狀態	含義	典型場景
400	請求錯誤	缺參、引數格式錯、模型不支援的欄位
401	未認證	缺失 / 錯誤 / 已停用的 Token
403	已認證但禁止	IP 不在白名單、Token 無權呼叫該模型
404	資源不存在	模型 ID 錯誤、檔案 ID 不存在
409	衝突	同名資源已存在
413	請求體過大	檔案、prompt、batch 超限
422	語義錯誤	JSON Schema 校驗未通過
429	限流 / 配額不足	RPM 超限、Token 額度不足、賬戶餘額不足
499	客戶端中斷	客戶端取消了請求
500	內部錯誤	WRouter 自身故障，可重試
502 / 503 / 504	上游異常	上游模型不可用 / 超時，建議重試或換模型

錯誤碼（error.code）

code	含義
invalid_api_key	Token 無效
expired_api_key	Token 已過期
disabled_api_key	Token 已停用
ip_not_allowed	IP 不在白名單
model_not_found	模型 ID 不存在
model_not_authorized	該 Token / 分組無權呼叫此模型
insufficient_quota	Token 配額耗盡
insufficient_balance	賬戶餘額不足
rate_limit_exceeded	觸發限流
content_policy_violation	違反內容安全策略
context_length_exceeded	輸入超出模型上下文視窗
upstream_error	上游返回錯誤（詳見 message）
upstream_timeout	上游超時
internal_error	WRouter 內部錯誤

重試建議

錯誤	是否可重試	備註
429	✓	指數退避，初始 1s，最長 60s
500 / 502 / 503 / 504	✓	同上
upstream_timeout	✓	減小 max_tokens 或換模型
4xx 其他	✗	修復請求再呼叫

OpenAI SDK 與 Anthropic SDK 預設帶有重試邏輯，可直接複用。

除錯

控制台 → 呼叫日誌 → 點選單條記錄 可檢視：

• 請求 / 響應體（脫敏後）
• 上游 endpoint、延遲、狀態碼
• 實際扣費明細
• 完整 trace ID

將 trace ID 一併提交給客服可極大加速問題定位。