错误码与重试

平台对所有接口采用统一的结构化错误体：无论数据平面还是控制平面，出错时都返回相同形态的错误对象，便于您在应用侧统一识别、本地化与重试。本页说明错误体结构、HTTP 状态码语义、平台特有错误码，以及按错误类型的退避重试建议。

错误体结构

出错时，响应体为如下结构（数据平面按所兼容协议的 error 对象形态返回，以兼容既有 SDK）：

{
  "error": {
    "code": "<字符串错误码>",
    "message": "<面向用户的可读说明>",
    "request_id": "<请求追踪标识>"
  }
}

优先按 code 判定。 请在应用侧以 code 字段做程序分支，message 仅用于展示——message 文案可能随版本优化，code 保持稳定。HTTP 状态码用于粗分类，code 用于细分原因。

HTTP 状态码语义

平台特有错误码

在 HTTP 语义之上，平台以 code 字段细分常见原因。下表为常见错误码（具体取值以实际响应为准）：

达额暂停（quota_exceeded / 429）。 平台采用单层汇总信用额度约束全部密钥，账户当月用量达上限时全部密钥一并暂停。此时数据平面查询返回 429，控制平面的查询、账单、额度等管理功能照常可用。额度核减、预警、达额恢复与提额详见 额度管理。

安全防护处置（guardrail_blocked）。 当请求或响应触发注入防护、敏感信息脱敏或应拒答处置时，平台返回结构化护栏处置结果。若正常请求被误判，请留存 request_id 并按 安全防护处置 · 误拒说明与申诉路径 提交申诉。

退避与重试建议

不同错误的可重试性不同，请按下表区别处理，避免无效重试造成请求堆积：

推荐的重试要点：

• 指数退避 + 抖动。 对 5xx 与 rate_limited，每次重试间隔按指数增长并加入随机抖动，避免重试风暴。
• 设重试上限。 为可重试错误设定最大重试次数（如 2~3 次），超过即转入告警与降级，不无限重试。
• 区分对待 429。 先看 code：rate_limited 退避后可重试，quota_exceeded（额度暂停）则应暂缓并告警、等待恢复，而非重试。
• 流式断流。 流式中途断开按 流式响应 · 断流与重试建议 处理；只有产出 usage 末帧的那次生成才计入用量。
• 留存 request_id。 任何需要反馈或申诉的错误，请连同 request_id 一并提供，便于平台定位。

示例：对 429 的区分处理。 收到 429 时，先读 error.code：若为 rate_limited，按退避重试；若为 quota_exceeded，识别为达额暂停后停止重试、触发内部告警，并在控制台查看额度状态、按需提交提额申请。

错误码与各能力页的对应