常見錯誤

錯誤回應格式

模型介面的錯誤以 JSON 回傳：

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

• message 是可讀說明，結尾帶 (request id: <id>)。同一個 id 也會出現在回應標頭 X-Oneapi-Request-Id 中，聯絡技術支援時請一併提供。
• code 是機器可讀的錯誤碼。部分錯誤該欄位為空字串，此時以 HTTP 狀態碼為準。
• message 會依使用者語言設定或 Accept-Language 本地化，且可能調整，程式邏輯請以 HTTP 狀態碼和 code 為準。

Claude Messages（/v1/messages）改用 {"type": "error", "error": {"type": "...", "message": "..."}}。非同步任務介面（/v1/video/generations、/v1/videos、/suno/*）在路由之後產生的錯誤回傳 {"code", "message", "data"}，且其中的 message 不帶 request id。

401 Unauthorized

API Key 缺少、無效、已過期、已停用或額度已用盡：

• 缺少 Authorization 標頭，或沒有寫成 Bearer sk-...。
• Key 被刪除、被停用或已過期。
• Key 的剩餘額度已用完。
• 在模型介面上傳了管理金鑰（rat_...）；呼叫模型必須使用 sk- 開頭的 API Key。

需要時請在控制台 API Keys 頁面新建 Key。Key 的額度與有效期限見儲值與額度。

403 Forbidden

403 有兩種完全不同的原因，請先看回應中的 code。

餘額或 Key 額度不足

• insufficient_user_quota：帳戶餘額不足以支付本次請求的預估費用，或訂閱額度已用完。
• pre_consume_token_quota_failed：Key 的剩餘額度不足以支付本次請求的預估費用。

請儲值、調高 Key 額度，或降低 max_tokens 讓預估費用落在額度內。詳見儲值與額度。

權限不足

這類錯誤的 code 通常為空，請以錯誤訊息區分具體原因：

• Key 的模型限制不包含該模型（This token has no access to model ...）。
• Key 所在分組對你的帳戶不可用。
• 來源 IP 不在 Key 的 IP 允許清單中（code 為 access_denied）。
• 帳戶已被停用。

429 Too Many Requests

觸發了請求頻率限制。限流按帳戶計算：同一帳戶下的所有 Key 共享額度，增加 Key 不會提高上限。被拒絕的請求不計費。

• 使用帶隨機抖動的指數退避重試。
• 降低併發，或把請求分散到更長的時間窗口。
• 429 的回應內容可能為空，請以狀態碼為準，不要依賴錯誤文案。

限流規則以及上游 429 的重試方式見用量與計費。

503 模型不可用

• code 為 model_not_found，訊息類似 “No valid upstream service”：目前沒有管道為你的分組提供該模型。請確認模型 ID 拼寫，以及該模型是否對你的帳戶開放；立即重試同一個請求通常沒有意義。

502 / 503 上游錯誤

• 模型服務商回傳的 502 或其他 5xx，在重試全部失敗後原樣回傳。
• code 為 get_channel_failed，訊息為 “Upstream service is temporarily unavailable”：管道背後的上游帳號不可用（例如餘額或憑證失效）。RouteAPI 會盡量換管道重試，仍失敗時回傳這則通用提示、觸發內部告警，並可能自動停用故障管道；請稍後重試。
• code 為 client_failfast（503）：同一個 API Key 對此模型的請求持續高比例失敗，平台為該 Key 與模型組合開啟了短時保護窗口。回應會帶 Retry-After 和 X-Client-Failfast: 1，請等待後再重試，並先修正失敗原因，而不是原樣重送。

臨時性錯誤請稍後重試；持續出現時請攜帶 request id 聯絡技術支援。