# 错误与恢复

发布 0.4.0 / API v1。HTTP 错误包含 `code`、`message`、`request_id`、`retryable`。按 `code` 判断，`message` 是给人看的一句英文说明，措辞可能调整，不要据它分支。保留业务引用和请求 ID，报告中不要包含密钥、原始终端用户数据或上游响应。

| 情况                                                                                         | 接入方行为                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 unauthorized                                                                             | 核对所属产品、密钥是否已撤销与私有配置；管理凭据不能替代产品 Key                                                                                                                                                                                                                               |
| 403 forbidden / csrf_failed                                                                  | 核对动作授权；后台产品调用使用产品 Key，Cookie 只用于同源管理界面                                                                                                                                                                                                                              |
| 404 not_found                                                                                | 核对当前用户与对象归属、所用服务入口；不通过跨用户遍历寻找对象                                                                                                                                                                                                                                 |
| 400 invalid_path                                                                             | 路径编码或长度不合法，属请求错误，不重试                                                                                                                                                                                                                                                       |
| 409 event_conflict                                                                           | 原 `event_id` 对应原内容；从本地持久记录恢复原内容重发，不能为绕过冲突而换 `event_id`                                                                                                                                                                                                          |
| 409 conflict / product_name_taken / config_version_conflict                                  | 名称或版本号已被不同内容占用，原请求重试不会成功；核对是否已创建，或换一个名称/版本号                                                                                                                                                                                                          |
| 409 account_closed                                                                           | 用量上报与下单（checkout）都拒绝：停止新收费工作；已记的用量不变；迟到付款不重新开通                                                                                                                                                                                                           |
| 409 product_archived                                                                         | 产品已归档，不再收款：checkout 与 `purchase-sessions` 都拒绝，读取与已有订单不受影响；请维护者确认产品状态                                                                                                                                                                                     |
| 422 unsupported_sku / amount_out_of_range / amount_not_accepted / unsupported_payment_method | 下单参数不被当前在售目录接受（sku 不在售；自定金额超出 min/max 或不合 step；固定额度包不接受 `amount`；收款方式未配置）。原样重试不会成功：重读 `catalog` 修正参数后再下单                                                                                                                     |
| 409 subscription_active                                                                      | 用户还有会续费的订阅（或一个未结束的订阅收银台）：先 `POST …/subscription/cancel` 设为到期取消，再关闭账户；关闭后到期前不会再发放额度                                                                                                                                                         |
| 409 subscription_exists / subscription_checkout_open                                         | 用户已有订阅：换档用 `POST …/plan`；另一个订阅收银台刚创建、还不能作废时，稍后重试                                                                                                                                                                                                             |
| 409 subscription_required                                                                    | 用户没有可操作的有效订阅（或从未开过订阅收银台，没有客户管理页）：引导去开通                                                                                                                                                                                                                   |
| 409 meter_changed                                                                            | 负责人修改了计量，这笔用量没有记账：重读 `catalog.config`，按新单位换算后重报（可沿用原 `event_id`），之后带新的 `meter_version`                                                                                                                                                               |
| 409 subscription_ending                                                                      | 订阅已设为到期取消，不能换档；先撤销取消（`POST …/subscription/resume`）再换                                                                                                                                                                                                                   |
| 409 plan_unchanged / plan_change_in_progress                                                 | 已是这个档位；或同一用户的另一次换档还在处理，稍后重读 `GET …/plan` 再决定                                                                                                                                                                                                                     |
| 409 plan_change_payment_failed                                                               | 升级的差价没扣成功（拒卡，或需要 3DS 验证），档位未变：请用户在客户管理页换一张卡后重试                                                                                                                                                                                                        |
| 409 billing_portal_not_configured                                                            | 负责人还没在 Stripe 后台保存过客户管理页设置                                                                                                                                                                                                                                                   |
| 422 unsupported_plan / free_plan_not_subscribable                                            | 档位不存在、已下架或是免费档：重读 `catalog` 的 `plans` 后再选                                                                                                                                                                                                                                 |
| 422 return_origin_not_configured / invalid_return_path                                       | 产品未配置 `return_origin` 时不能传 `return_path`；`return_path` 须是以单个 `/` 开头、不含 `#` 与控制字符的站内路径。省略 `return_path` 或请维护者配置回跳地址                                                                                                                                 |
| `allowed: false`（200）                                                                      | 余额已用完或有欠额：停止当前工作，展示充值入口；下一笔充值先抵扣欠额                                                                                                                                                                                                                           |
| 429 try_again_later                                                                          | 托管充值页：同一会话 15 分钟内下单超过 20 次，`Retry-After` 给出本窗口剩余的秒数，由付款人到时在页面重试，产品后端不代为重发。任何接口：同一来源地址每分钟请求过多（带产品 Key 的请求与 Stripe 通知超过 6000 个，其余超过 1200 个，按 Cloudflare 节点计），`Retry-After: 60`，按原请求稍后重试 |
| 410 topup_session_expired                                                                    | 链接已过期，不能继续使用；回产品查原订单，需要时重新签发                                                                                                                                                                                                                                       |
| 503 stripe_not_configured                                                                    | 联系 Billing 维护者配置 Stripe；用量上报不依赖 Stripe                                                                                                                                                                                                                                          |
| 503 stripe_unavailable                                                                       | 建单时 Stripe 暂时不可用，订单保持 `creating`：用同一个 `purchase_ref` 重试，得到同一个订单与收银台                                                                                                                                                                                            |
| timeout / service_unavailable                                                                | 不推断零消费或付款失败；读取原记录，用原 `event_id`/`purchase_ref` 有限重试相同请求（不需要也不读取 `Idempotency-Key`）                                                                                                                                                                        |

用量上报失败时，保留这一段用量和它的 `event_id`，下一轮用原内容重发；SDK 的 `createMeter` 已这样做。进程崩溃最多丢一个上报间隔的用量（对商户是少收，不是多收）。不要为了"保险"换一个 `event_id` 重报同一段用量。

关闭账户前，产品先停止该用户的新工作、报完剩余用量，并把会续费的订阅设为到期取消。关闭后上报返回 `account_closed`，已记的用量和欠额保持不变。

Billing 实例的恢复由维护者操作（Cloudflare Durable Object 按时间点恢复）；恢复期间不接受新用量。客户端不能通过赠金、改余额或换引用来绕过。