速率限制与错误
各项限制，以及每个状态码的含义。
429 可能来自多个层面：
- 我们的免费模型上限：每个用户、每个免费模型每分钟 1 次请求。
- 上游限制：免费模型背后的提供商触发了它自己的上限。
- 部分免费池设有每日 token 预算，在 UTC 零点重置。
- 每分钟 token 上限，超大提示词会触发。
- 针对并行请求的按用户并发限制。
付费模型没有由 UnoRouter 施加的速率限制。
触发每分钟 1 次的上限时，你会收到标准的速率限制请求头：
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After 是你当前窗口剩余的秒数，而不是固定的 60。提示信息会指出对应的付费模型，它没有这个限制。
部分付费模型以带请求大小上限的方式免费提供。超长提示词会返回 413：Request body too large for gpt-4.1 model. Max size: 8000 tokens。
该上限只作用于免费线路。付费模型接受完整长度的提示词。
错误以 OpenAI 错误格式的 JSON 返回。code 是稳定的标识符。每条消息末尾都会附上请求 id：
{
"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"
}
}提交支持工单时请附上请求 id。它能在日志中定位你的请求。
如果你还在配置密钥或基础 URL，请先阅读 快速入门
你实际会遇到的状态码：
| 状态码 | 含义 | 应对方法 |
|---|---|---|
400 | 无效请求：参数有误，或提示词被审核拦截。 | 请修正请求。原样重试仍会失败。 |
401 | 密钥缺失、无效、已过期或已停用。 | 请检查 Authorization 请求头和 Tokens 页面。 |
402 | 此密钥自身的支出上限已用尽。 | 提高该密钥的上限，或创建一个新密钥。 |
403 | 余额为零、该密钥不允许使用此模型，或 IP 不在白名单中。 | 充值，或检查密钥的模型与 IP 限制。 |
413 | 请求超出了该模型免费试用的大小上限。 | 缩短提示词，或切换到付费模型。 |
429 | 触发了某种速率限制（见下方各类）。 | 等待 Retry-After 指定的秒数，然后重试或切换模型。 |
500 | 我们这边或上游提供商出了问题。 | 稍等片刻后重试。若 500 持续出现，请反馈给我们。 |
503 | 所有提供商都很繁忙，或者模型名称不存在。 | 请看提示信息：繁忙几分钟就会缓解，拼写错误不会。 |
两种截然不同的情况共用状态码 503。第一种是临时拥塞：
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 当作可重试的错误，把 model_not_found 当作确定性的错误。
因负载消失的模型会自行回归；想在它回归的那一刻收到提醒，请在这里关注它： 通知
如果你的密钥固定了提供方分组，还有第三种 503：只有你固定的分组宕机时出现，见： 分组固定
遇到 429 时请遵守 Retry-After。遇到 503 get_channel_failed 时稍等再重试，或换个模型。400 类错误不要重试。
失败和被拒绝的请求绝不计费；预扣和退款的机制见： 账户与计费