错误码与限流

错误按你调用的协议返回：OpenAI 兼容接口（/v1/chat/completions、/v1/responses、/v1/embeddings、/v1/videos 等）按 OpenAI 的定义，Anthropic 兼容接口（/v1/messages）按 Anthropic 的定义。官方 SDK 可以直接按各自的异常类处理。

错误结构

OpenAI 兼容接口：

{
  "error": {
    "message": "Your organization's balance is used up — top up in the console to continue; retrying will not help（组织余额已用完，请在控制台充值后继续；重试无效）",
    "type": "insufficient_quota",
    "param": null,
    "code": "credit_balance_exhausted",
    "goodput_reason": "balance_exhausted",
    "goodput_scope": "org"
  }
}

Anthropic 兼容接口（/v1/messages、/v1/messages/count_tokens）：

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Your organization's balance is used up — …（组织余额已用完…）",
    "goodput_reason": "balance_exhausted",
    "goodput_scope": "org"
  },
  "request_id": "5b1d…"
}

错误码对照

额度类错误

balance_exhausted 与 spend_limit_reached 的区别在于钱是不是真的没了：前者是付款方（个人账户或组织）的余额用完，后者是某一层设定的上限到了、余额可能还有。goodput_scope 说明撞的是哪一层：

重试建议

错误响应会带上重试相关的头，官方 SDK 会自动遵守：

• x-should-retry: false：重试没有意义（参数错、Key 无效、余额或额度用完等）。官方 OpenAI / Anthropic SDK 看到它就不会自动重试。
• retry-after：限流、过载时建议等待的秒数。

跨模型容灾建议直接用请求级 fallbacks 参数，由网关自动完成切换。

流式请求中的错误

• 还没有输出任何内容就失败时，返回的是普通的错误响应（真实状态码 + 上面的 JSON 结构）。
• 已经开始输出后才失败时，HTTP 状态码已是 200，错误以一个事件发出：OpenAI 兼容接口是 data: {"error": {…}}，Anthropic 兼容接口是 event: error + 上面的 Anthropic 结构。官方 SDK 都会把它转成异常。

限流策略

限流按账户与项目层级设定（请求频率与 token 速率双维度）。组织管理员可在控制台为项目配置独立限速。

报障时提供什么

每个错误响应都带请求 ID：响应头 x-goodput-request-id（OpenAI 兼容接口另有 x-request-id，Anthropic 兼容接口另有 request-id，body 里也有 request_id）。它和控制台「调用日志」里的 request_id 是同一个（见用量与调用日志）。报障时连同时间点、模型 ID 一起提供给支持人员，可以最快定位问题。