幂等与重试
所有改变状态的请求都必须携带 X-Idempotency-Key 或 Idempotency-Key，至少一个。两者同时发送时必须相等；签名优先覆盖 X-Idempotency-Key。
生成规则
为一次业务操作生成稳定的键，并在重试时沿用。merchant_order_id 是商户订单身份，与 Header 幂等键是两个不同字段。创建 Invoice 以账户内的 merchant_order_id 和请求内容识别重试，不使用网关的 Header 响应缓存；Transfer 与退款还会以 Header 键判断业务重试。信用卡授权、捕获和退款另有请求体 idempotency_key，建议与 Header 使用相同值。
text
invoice:create:ORDER_20260827_001
transfer:create:PAYOUT_20260827_0042
invoice:refund:REFUND_20260827_0007安全重试流程
- 请求超时或连接断开时，不要立即生成新订单号。
- 使用相同 body、商户订单号和 Header 幂等键重试。
- 刷新
X-Timestamp并重新签名。 - 若结果仍不确定，通过 Query API 按资源 ID 或商户订单号确认。
冲突处理
同一 Header 幂等键在网关响应缓存有效期内配合不同 body 会返回 422 VALIDATION_ERROR；业务层的订单号或幂等键冲突可能返回 409 CONFLICT。两种情况都应停止自动重试，核对原请求。创建 Invoice 的重试首先依据账户内的 merchant_order_id，不能仅凭更换 Header 键创建新订单。
| 状态 | 是否自动重试 | 建议 |
|---|---|---|
| 网络超时 / 连接重置 | 是 | 相同幂等键，指数退避并加入 jitter |
429 Too Many Requests | 是 | 遵循 Retry-After |
500 / 502 / 503 / 504 | 有限重试 | 相同幂等键，最终转 Query 确认 |
400 / 401 / 403 | 否 | 修复请求或凭证配置 |
409 | 否 | 检查幂等键与原始 payload |
422 | 否 | 检查幂等键是否配合了不同 body，或支付 Rail 是否可用 |