错误码与计费

错误响应格式

所有错误统一为：

{ "error": { "type": "...", "code": "...", "message": "..." } }

上游服务自身返回的错误会以 upstream_error 类型透传，不会被网关改写。

402 响应示例

Strict 模式预扣失败时，error 对象内额外带 requiredUsd 字段，表示本次请求需要预留的金额（美元）：

{
  "error": {
    "type": "insufficient_funds_error",
    "code": "strict_reserve_failed",
    "message": "Insufficient balance to reserve for this request.",
    "requiredUsd": 1.25
  }
}

Flex 模式的 flex_threshold_breached 响应为标准 error 对象，不带额外字段。

计费规则

按 token 计费

每次成功请求按四类 token 分别计费，各模型费率见定价：

不计费的请求

• 失败请求：4xx / 5xx / 超时（网关默认上限 300s）一律不扣费。
• POST /v1/messages/count_tokens：token 估算端点，不计费。
• GET /v1/models：模型列表端点，不计费。

流式中断

流式请求中断时，若已观测到至少一帧输出，则按已观测到的 token 数计费，并在用量记录中标记 estimated。若中断前没有任何输出，按失败请求处理，不扣费。

余额模式

组织有两种计费模式：

• Flex（弹性）：余额高于阈值时正常放行，低于阈值（默认 $100）拒绝新请求（402 flex_threshold_breached）。
• Strict（严格）：每次请求前按预估上限预扣，余额不足直接拒绝（402 strict_reserve_failed）；请求结束按实际用量结算多退少补。

余额跌破阈值会自动从 Flex 切到 Strict；回升到阈值的 1.2 倍以上再切回，避免来回抖动。

Flex vs Strict 对比

余额与充值

余额属于组织级共享余额池，组织内所有成员的 Key 消耗同一份余额。在 /account/billing 可查看当前余额并通过 Stripe 充值。

错误处理建议