幂等与重试

所有改变状态的请求都必须携带 X-Idempotency-Key 或 Idempotency-Key，至少一个。两者同时发送时必须相等；签名优先覆盖 X-Idempotency-Key。

生成规则

为一次业务操作生成稳定的键，并在重试时沿用。merchant_order_id 是商户订单身份，与 Header 幂等键是两个不同字段。创建 Invoice 以账户内的 merchant_order_id 和请求内容识别重试，不使用网关的 Header 响应缓存；Transfer 与退款还会以 Header 键判断业务重试。信用卡授权、捕获和退款另有请求体 idempotency_key，建议与 Header 使用相同值。

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 是否可用