幂等与重试
幂等用于避免同一业务操作在重试时重复执行。GoodVision 写请求使用稳定的 Idempotency-Key，重复提交相同请求时不会产生重复结果。
网络超时后，服务端可能已经完成操作。请保留原请求内容和幂等键，按以下步骤恢复。
一个业务操作只生成一次 Key
用户发起操作时生成一个不可预测的 Key，将它和本地业务记录一起持久化。相同请求的所有重试必须复用这个 Key。
http
POST /v1/oem/subscriptions/sub_opaque/cancel HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Idempotency-Key: 9a87c940-69a6-4b86-bf20-bca5cabd66d7
Content-Type: application/json
{"cancel_mode":"end_of_period"}同一个 Key 不能用于不同 Payload。Key 已绑定其他请求内容时，服务端可返回 409 Conflict。
超时后的处理顺序
- 使用原 Key 和完全相同的 Payload 重试。
- 如果已获得
operation_id，查询该异步操作。 - 查询当前资源状态，确认原操作是否已经生效。
- 只有用户明确发起一个新的业务操作时，才生成新 Key。
不要因为超时就换 Key 重复创建订单、取消请求或支付/退款操作。
哪些错误可以重试
| 情况 | 处理方式 |
|---|---|
| 网络错误或超时 | 原 Key、原 Payload，有界指数退避 |
429 | 遵守 Retry-After，增加随机抖动 |
契约明确可重试的 5xx | 有界重试，之后查询操作或资源状态 |
400 / 422 | 修正输入后作为新操作提交 |
401 / 403 | 修复认证或授权，不要原样重试 |
409 | 读取当前状态，处理版本或幂等冲突 |
Webhook 也需要幂等
Webhook 按“至少一次”投递，同一事件可能出现多个 Delivery。使用 event_id 去重，使用 resource_version 防止旧事件覆盖新状态；delivery_id 只标识一次投递尝试。