平台指南

錯誤與速率限制

每個狀態碼的含義以及因應方法。

錯誤格式

錯誤以 OpenAI 錯誤格式的 JSON 回傳。message 說明發生了什麼，code 是一個穩定、機器可讀的識別碼，而且每則訊息都會附加一個請求 id：

json

{
  "error": {
    "message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "model_not_found"
  }
}

聯絡支援或在 Discord 開工單時，請務必附上請求 id。它能讓我們在記錄檔中找到你確切的那次請求。

狀態碼一覽

你實際會遇到的狀態碼：

狀態碼	含義	因應方法
`400`	無效請求：參數值錯誤（例如 max_tokens 低於模型最小值），或提示詞被內容審核攔截。	修正請求。原樣重試仍會失敗。
`401`	金鑰問題：API 金鑰遺失、無效、已過期或已停用。	檢查 Authorization 標頭，以及權杖頁面上的金鑰。
`402`	此金鑰自身的支出上限已用盡。	提高該金鑰的上限，或建立一個新金鑰。
`403`	存取遭拒：帳戶餘額為空、該金鑰不允許使用此模型，或你的 IP 不在金鑰的允許清單中。	儲值，或檢查金鑰的模型與 IP 限制。
`413`	請求超出此模型免費試用上限。	縮短提示詞，或切換到付費模型。
`429`	觸發了某種速率限制（見下方各類）。	等待 Retry-After 指定的秒數，然後重試或切換模型。
`500`	我們這邊或上游供應商出了問題。	稍候後重試；持續出現的 500 值得回報。
`503`	該模型的所有供應商都忙碌，或該模型名稱不存在。	閱讀訊息：忙碌會在幾分鐘內緩解，拼字錯誤不會。

503：忙碌與未知模型

兩種截然不同的情況共用狀態碼 503。第一種是暫時壅塞：

text

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "get_channel_failed"
  }
}

錯誤碼 get_channel_failed（所有供應商忙碌）表示該模型的每個免費供應商都暫時被速率限制。這會在幾分鐘內自動恢復：請重試或切換模型。錯誤碼 model_not_found（此處未提供）表示模型名稱本身無法解析，重試永遠無濟於事。請檢查拼字，或在目錄中查找目前名稱。

在你的用戶端裡，把帶 get_channel_failed 的 503 當作重試或回退，把帶 model_not_found 的 503 當作硬錯誤。

速率限制的種類

429 可能來自多個層面：

我們的免費模型上限：每位使用者每個免費模型每分鐘 1 次請求。這是一個公平性上限，讓共享池在尖峰時段得以維持。
上游供應商限制：免費模型背後的供應商達到了它自己的上限（"temporarily rate-limited upstream"，即上游暫時被速率限制）。
某些免費池的每日權杖預算；它們在 UTC 午夜重設。
每分鐘權杖數上限，在非常大的提示詞上觸發。
當並行執行的請求過多時，針對每位使用者的並行上限。

付費模型沒有由 UnoRouter 施加的速率限制。

免費模型限制詳解

當我們每分鐘 1 次的上限觸發時，你會收到標準的速率限制標頭，以便用戶端能精確地退避：

text

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After 是動態的：它是你視窗中實際剩餘的秒數，而非固定的 60。錯誤訊息還會指出該模型對應的付費孿生模型，後者沒有限制。

試用大小上限

一些通常付費的模型以帶請求大小上限的方式免費提供。過大的提示詞會收到 413，附帶類似訊息：Request body too large for gpt-4.1 model. Max size: 8000 tokens.

該上限僅適用於免費試用路徑；付費模型接受完整長度的提示詞。

重試指引

對 429 請遵守 Retry-After。對 503 get_channel_failed 在短暫等待後重試，或回退到另一個模型。不要重試 400 類錯誤，它們是確定性的。

失敗和被拒絕的請求不會計費：當請求出錯時，對你餘額的任何預扣都會退回。