两条核心契约
- 失败不计费。 任何非 2xx 响应都免费。
X-Quota-Remaining-Credits不动；/api/v1/me/usage里没有新行；/api/v1/me/billing/transactions里没有新条目。硬契约 —— 无例外。 - 错误以你调用的协议信封返回。
/v1/messages上 Anthropic 形状；/v1/chat/completions+/v1/responses+/v1/tasks/*+/v1/images/*上 OpenAI 形状；/v1beta/...上 Google 形状。
状态码分类
每个 code 的细节表（含机器可读的
code / type enum）在 Errors reference。
重试策略
- 429： 用
X-RateLimit-Reset（Unix 时间戳）—— 别猜。对并发 429，用短的抖动退避（1-3s），上限随 in-flight 请求完成而清。 - 5xx： 指数退避，从 1s 起 —— 4 次后放弃。网关在透出之前已经做过内部重试。
- 4xx（除 429 外）： 别重试。同一请求会以同样方式再失败一次。
幂等性
文本端点（/v1/messages、/chat/completions、/responses）不 幂等 —— 200 之后重试会再扣一次钱。除非拿到非 2xx，否则别重试。
异步任务 API（/v1/tasks/submit）通过 out_task_id 实现 幂等。重试时发同样的 out_task_id 会返回已有的任务，而不是开新的。见 tasks/submit。
流式中错误（SSE）
如果流中途失败，你会看到一个最终的event: error（Anthropic 形状）或带 error 字段的最终帧（OpenAI 形状），然后连接关闭。失败前已收到的部分输出归你，但请求 不计费 —— 即便中途失败，“不计费” 契约也完整适用。
SSE 没有 resume —— 需要恢复就从头重发请求。
异步任务失败
进到failed（而不是 completed）的任务不计费。/tasks/query 响应里的 error_code + error_message 字段告诉你发生了什么。取消的行为取决于取消前的状态 —— 见 tasks/cancel。
另见
- Errors reference —— 完整的 HTTP 状态 + code 矩阵，三种信封形状并排
- 速率限制 —— 什么触发 429 + 如何退避
- Credits 与账单 —— 完整的 “不计费” 保证
- 流式 —— 流中错误的语义