平台指南

错误与速率限制

每个状态码的含义以及应对方法。

错误格式

错误以 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 类错误，它们是确定性的。

失败和被拒绝的请求不会计费：当请求出错时，对你余额的任何预扣都会退回。