错误处理
API 使用 HTTP 状态码区分错误类型。调用方应同时记录状态码、错误 code、可公开的 message、请求时间和本地关联 ID；不要记录凭证或完整敏感 body。
| HTTP | 含义 | 处理建议 |
|---|---|---|
| 400 | 参数不合法、缺少 X-API-ID 或两个幂等 Header 不一致 | 修正请求，不自动重试 |
| 401 | 缺少 X-API-Key、凭证无效、签名、时间戳、Host 或 credential kind 错误 | 检查签名材料和服务路由 |
| 403 | 已认证但 Scope 不足 | 申请最小必要权限 |
| 404 | 资源不存在或对当前账户不可见 | 核对 ID 与账户边界 |
| 409 | 幂等冲突或状态冲突 | 查询原请求结果，停止盲重试 |
| 422 | 同一幂等键配合不同 body，或支付 Rail 已停用等语义错误 | 核对原请求与当前可用 Rail，不自动重试 |
| 429 | 触发限流 | 遵循 Retry-After，指数退避 |
| 5xx | PSP 或上游暂时异常 | 有限重试，并通过 Query 确认最终状态 |
若新订单选择的支付分类已停用，PSP 会在订单被接受前返回 422 PAYMENT_RAIL_INACTIVE。 调用方应刷新可用支付方式并重新选择；不要据此停止处理已接受订单，历史订单和在途订单继续按创建时冻结的分类与执行配置推进。
可观测性建议
- 为每次业务意图生成本地 correlation ID。
- 记录 PSP 返回的资源 ID 与商户订单号映射。
- 将重试次数、最终 HTTP 状态和耗时做成指标。
- 对签名失败、幂等冲突、Webhook 堆积和状态长时间未收敛配置告警。