OneProvider

错误码

读懂 OneProvider 的每个错误：各状态码的含义、确切的错误信息、时间限制、流式过程中的错误，以及何时可以安全重试。

各状态码的含义、您会看到的确切错误信息，以及下一步该怎么做。

全部模型、功能与价格 面向 AI 智能体的文档索引： https://oneprovider.dev/docs/llms.txt

错误结构

在所有端点（/v1/messages、/v1/chat/completions、/v1/responses、/v1/models）上，每个错误都是结构相同的 JSON。余额错误还会带有 code：

json 
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}

OpenAI SDK 会照常从该响应体读取 error.message，所以在任何客户端里您看到的都是同样的文字。

状态码

参考数据
状态error.type信息与含义处理方法
400invalid_request_error 请求格式有误：JSON 无效、缺少字段，或值不被允许。错误信息会指出具体问题。 请按错误信息的提示修正后重新发送。原样再发一次会得到同样的错误。
400invalid_request_error prompt is too long: N tokens > M maximum 输入内容超出了该模型的上下文窗口。N 和 M 取决于具体模型。 请缩短历史记录或附件，或选择上下文更大的模型。Claude Code 遇到这种情况时会自动压缩对话。
400invalid_request_error Model X is not available on this API key 您密钥的方案不包含此模型。 请选择 GET /v1/models 返回的模型，或价格页面上列出的模型。
401authentication_error Invalid API key API key is required 密钥缺失、拼写有误，或放在了错误的请求头中。 请将完整的 sk-… 密钥放在 x-api-key 或 Authorization: Bearer 中，不要带引号或空格。
401authentication_error API key is disabled 密钥已被停用，或账户未启用。 请在个人中心的“密钥”页面检查该密钥，或联系 @Oneproviderhelpbot。
403permission_error API key expired 密钥已过有效期。 请在个人中心的“密钥”页面延长该密钥，或签发新密钥。
404not_found_error The requested API endpoint does not exist 通常是 base URL 不对，例如路径中出现了 /v1/v1。 Claude Code 和 Anthropic SDK：https://api.oneprovider.dev。OpenAI SDK 和兼容 OpenAI 的客户端：https://api.oneprovider.dev/v1。
413invalid_request_error request body exceeds size limit 请求体超过 32 MB。 请发送更小或更少的图片和文件，或将任务拆分为多个请求。
429insufficient_balance Insufficient balance on this API key. Top up: dashboard.oneprovider.dev 个人中心余额或密钥的消费限额已用完。响应体中带有 error.code insufficient_quota，且响应头包含 x-should-retry: false。 请不要重试。请为个人中心充值（在机器人或 app.oneprovider.dev）或提高密钥的限额，然后重新发送请求。
429rate_limit_error Rate limit exceeded; retry later 短时间内请求过多。响应中可能带有 Retry-After 请求头。 如果有 Retry-After，请等待相应的秒数；否则请以逐渐延长的间隔重试。如果持续出现，请减少并行发送的请求。
500, 502server_error Service temporarily unavailable; retry later 我们这边出现了临时故障。 请以逐渐延长的间隔重试。
503server_error Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later 临时问题。您的密钥和请求都没有问题。 请以逐渐延长的间隔重试；通常不超过一分钟就会恢复。
504server_error Service timed out; retry later 请求超出了时间限制（见下文）。 请重试。生成较长回答时，请开启 stream: true。

时间限制

  • 非流式请求开始返回的时间不得超过 6 分钟。
  • 任何请求（包括流式请求）最长为 10 分钟。
  • 生成较长内容时请使用 stream: true：流式请求会立即开始返回。如果一个回答需要超过 10 分钟，请拆分任务。

流式输出中的错误

流式输出一旦开始，状态码已经是 200，因此错误会以事件的形式到达。Messages API 会发送带有相同错误体的 event: error 帧；Responses API 会发送 response.failed 事件，原因在 response.error 中。

text 
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}

请按对应状态码的方式处理。已返回的部分回答并不完整：如果该错误可重试，请重新发送整个请求。

何时重试

  • 先修正，不要重试：400、401、403、404、413，以及带有 insufficient_balance 的 429。在您修改请求、密钥或余额之前，同样的请求会一直以同样的方式失败。
  • 以逐渐延长的间隔重试：429 rate_limit_error、500、502、503、504。例如 1 秒、2 秒、4 秒，依此类推，最长到一分钟，并加入少量随机抖动。如果有 Retry-After，请至少等待这么长时间。
  • 请遵守 x-should-retry: false。官方的 Anthropic 和 OpenAI SDK 已经这样做了，因此不会重试余额错误。
  • 可用 GET /v1/dashboard/balance 查看剩余余额，详见用量与计费 。

常见客户端的表现

  • Claude Code. 在会话中显示该错误信息。遇到 401 后，Claude Code 2.1.231 及更新版本会删除已保存的密钥：请检查密钥和 base URL（https://api.oneprovider.dev，不带 /v1），然后重新设置密钥。遇到余额错误时会立即停止：请充值后继续。遇到 "prompt is too long" 时会自动压缩对话。临时的 429 和 5xx 错误会自动重试。
  • Cursor. 在聊天中显示错误文本。请在模型设置中检查 API 密钥和 base URL https://api.oneprovider.dev/v1；如果提示的是余额问题，请先充值，然后重新发送。
  • Codex. 余额错误会显示为 "Quota exceeded" 并停止运行：请充值后重新运行命令。临时错误会先自动重试。
  • Cline. 在任务中显示错误，并带有“Retry”（重试）按钮。请先修正密钥、base URL 或余额，再点击“Retry”。
  • Continue. 在聊天面板中显示错误文本。请排除原因后重新发送消息。
最后更新: 2026-11-08 发现问题？ @Oneproviderhelpbot