错误码与限流

错误响应结构

json

{
  "error": {
    "code": 401,
    "message": "unauthorized",
    "metadata": {
      "request_id": "req_xxx",
      "error_class": "auth",
      "app_error_id": 4011
    }
  },
  "trace_id": "..."
}

错误响应体除了 error 对象外，还带一个与 X-Trace-ID 响应头一致的顶层 trace_id 字段（链路追踪关闭时省略），便于按日志检索。metadata.reason 是可选细分原因（例如 model_not_in_catalog）。完整清单与已验证示例见接口清单。

常见错误分类

error_class	HTTP	含义
`client_invalid`	400	请求格式或参数无效
`model_protocol_not_offered`	400	该逻辑模型未声明当前入口对应的 `public_protocols`（`app_error_id=4005`）。换入口或换模型，不要改写请求体撞协议
`provider_invalid`	400	上游拒绝请求（上游返回非 401/403/408/429 的 4xx）
`provider_unsupported`	400	上游不支持该接口（例如部分视频模型不支持 `DELETE` 取消）
`provider_timeout`	408	上游请求超时
`auth`	401	API Key 认证失败
`billing_insufficient`	402	余额不足
`policy`	403	无权调用该模型或未绑定策略
`quota`	429	触发平台配额或限流
`provider_rate_limit`	429	上游触发限流（上游返回 429）
`gateway_internal`	500	网关内部错误（兜底分类）
`billing_system`	502	计费系统不可用
`provider_server`	502	上游服务错误
`provider_unauthorized`	502	上游凭证被拒（统一归为 5xx，不向调用方暴露上游 Key 问题）
`provider_unavailable`	503	无可用模型供应方
`route_unconfigured`	503	模型路由未配置上游

失败请求的计费规则

预扣：每次请求受理后按预估用量冻结余额，请求结束后按实际用量结算，多冻结的部分立即释放。
成功请求与已交付部分内容的流式请求：按实际返回的用量结算。
请求已发往上游供应方但最终失败（上游 4xx/5xx、上游超时、流中途断开，以及客户端在等待响应期间主动断开）：按本次请求的预扣金额结算，不再退回。上游供应方对这类请求已产生实际成本，平台按预扣口径承担并向调用方收取。
请求尚未发往上游即被平台拒绝（参数校验、鉴权、策略、配额、余额不足、网关内部错误）：预扣全额释放，不产生费用。
结算依据可在控制台用量明细的交易记录中查看，按预扣结算的记录会标注失败原因。

排障建议

保留响应头中的 X-Request-ID 与 X-Trace-ID；错误响应体也会带同值的顶层 trace_id 字段
遇到 429 时结合 Retry-After 响应头做退避重试（平台限流命中时会下发该头）
流式请求若收到带 error 字段的数据块，应按失败处理（此类流中断对应 provider_stream_broken，不会再以独立的 HTTP 状态码返回）

能力接口的细节见：