自带 Key（BYOK）已上线，每月 1,000,000 次免费 BYOK 请求，不需要充值了解详情
EN 登录 开始使用

开发文档

报错与换线

每个报错都有 HTTP 状态码和一个便于程序判断的错误码。有些报错在你看到之前就已经处理过：承接请求的线路出错时，会换另一条线路再试同一个模型。

报错格式

Chat Completions 与 Responses
{
  "error": {
    "message": "Insufficient credits.",
    "type": "insufficient_balance",
    "code": "insufficient_balance"
  }
}
  • /v1/chat/completions 和 /v1/responses 使用上面的 OpenAI 格式，部分报错还会带 param。
  • 鉴权和限额类报错使用 {"error": {"code": ..., "message": ...}}。
  • /v1/messages 使用 Anthropic 的格式，HTTP 状态码和报错信息相同。见 Messages。

鉴权与限额

状态码错误码含义
401missing_api_keyAuthorization 和 x-api-key 里都没有 Key。
401invalid_api_key无法识别这个 Key。
403disabled_api_keyKey 已停用。请在控制台重新启用或新建一个。
403expired_api_keyKey 已过有效期。
403organization_frozen组织已被冻结或停用，请联系客服。
429org_rate_limit_exceeded整个组织一分钟内超过 600 次请求。请按 retry-after 响应头给出的秒数稍后重试。
429key_rate_limit_exceeded触发了你在控制台给这个 Key 设的每分钟上限。没设上限的 Key 只计入组织的 600 次。请按 retry-after 响应头给出的秒数稍后重试。
429key_spend_limit_exceededKey 达到了控制台里设的每日或每月花费上限。可以调高上限，或者等待：retry-after 指向下一个 UTC 日或月。

请求与余额报错

状态码错误码含义
400invalid_request请求体不符合接口格式，例如缺少 model，或 n 不等于 1。
400unsupported_parameter带了无法支持的字段，例如 audio、store: true 或 previous_response_id。能定位到字段时，param 会给出字段名。
400model_not_found目录里没有这个模型 ID。
400context_length_exceeded输入超出模型上限。报错信息会写明上限和估算值。
400model_price_not_configured这个模型暂时无法计费，请联系客服。
402insufficient_balance余额不够覆盖这个请求。见 余额与 max_tokens。
400byok_credential_required这个模型只能用你自己的 Key 调用，而账号里没有该厂商可用的 Key。
402byok_quota_exhausted只能用自带 Key 调用的模型上，本月的 BYOK 请求额度已经用完。每月 1 日（UTC）重置。
400byok_billing_config_incomplete这个只能用自带 Key 调用的模型暂时无法计费，请联系客服。

来自模型线路的报错

状态码错误码含义
502provider_error模型服务出错，尝试过的每条线路都失败了。
504provider_timeout请求超时。见 时限。
429provider_rate_limited模型服务在限流，尝试过的每条线路都是如此。请退避后重试。
4xxprovider_invalid_request模型服务拒绝了这个请求本身，例如模型不接受某个参数。状态码和报错信息按收到的原样返回。

模型服务返回了自己的报错原文时，message 会保留原话，这样根据特定报错文字做处理的客户端库（例如超出上下文后自动恢复）可以照常工作。

换线

承接请求的线路出错时，BoostRail 会在向你发送任何内容之前，换另一条线路再试同一个模型。不会换成别的模型。

  • 会换线：服务端错误、限流，以及线路拒绝了 BoostRail 自己的访问。
  • 不换线：provider_invalid_request，因为换一条线路也会拒绝同样的请求；以及非流式请求超时，因为已经超时的请求换线后还会超时。
  • 流式请求：45 秒内没有收到第一个事件，就换到下一条线路。最后一条尝试的线路不设首个事件时限。
  • 一旦已经向你发送了任何数据，请求就不再换线。
  • 所有线路都失败时，你收到最后一次尝试的报错，冻结的余额退回，不收任何费用。
  • 出过错的线路，在它恢复成功之前，后续请求会把它排在最后尝试。

已经开始返回数据后中断的流式请求，按 价格页 的规则计费。

时限

请求时限结果
非流式180 秒504 provider_timeout，不换线。
流式，首个事件每条线路 45 秒换到下一条线路；最后一条线路不设首个事件时限。

会话保持

会话 ID 相同的请求，会尽量留在这个会话上一次成功请求所用的线路上，有利于提示词缓存命中。会话 ID 依次从这几处读取：x-claude-code-session-id 请求头、x-session-id 请求头，然后是 user（Chat Completions 和 Responses）或 metadata.user_id（Messages）。

什么时候重试

  • 400 和 402：先改请求或补余额，原样重试结果不会变。
  • 429 并带 retry-after：等待对应的秒数。
  • 502、504 和 provider_rate_limited：按指数退避重试。BoostRail 这边已经尝试过换线。
  • 联系客服时请附上 x-request-id 的值。

更新日期：2026-10-05