错误码与重试

排查时提供 错误码、HTTP 状态、请求 ID。不要提交完整 API Key、私钥或敏感响应明文。

错误处理

错误码	处理方式
`API.KEY_INVALID`	核对凭证及目标环境
`API.KEY_LOCKED`	在开发者中心核对 API Key 状态，必要时联系平台
`API.IP_NOT_ALLOWED`	核对服务器实际出口 IPv4 和白名单
`API.VERSION_REQUIRED`	补充必填请求头 `X-API-VERSION`
`API.VERSION_UNSUPPORTED`	使用目标环境支持的 API 版本
`API.TIMESTAMP_REQUIRED` / `API.TIMESTAMP_INVALID`	使用 Unix 毫秒时间戳
`API.TIMESTAMP_EXPIRED`	校准服务器时间并重新签名；保持 NTP 同步
`API.NONCE_REQUIRED` / `API.NONCE_REUSED`	使用 SDK 生成新的 nonce
`API.SIGNATURE_INVALID`	核对协议版本、规范串、query、原始 body 字节及 RSA padding
`ACCESS.PERMISSION_DENIED`	核对 API Key 的接口权限
`VALIDATION.INVALID_PARAMETER`	核对必填项、类型、枚举及业务 ID；加密请求还需核对密钥指纹、AAD、信封及加密参数
`REQUEST.CONFLICT`	查询原操作结果；不要修改内容后复用同一幂等键
`REQUEST.RATE_LIMITED`	按 `Retry-After` 退避

SDK 本地异常与平台错误应区分记录。响应验签失败时不得使用响应体，也不能关闭验签继续调用。

响应头可能因网关或失败位置不同而缺失。

认证、参数和权限错误先修正原因，不盲目重试。

网络错误、429、5xx 使用有上限的退避重试；写操作须先确保幂等，结果不明时先查询。

同一业务重试复用原幂等键及相同业务内容，每次发送生成新的时间戳、nonce 和签名。

超时不等于业务失败，避免生成新幂等键造成重复执行。

签名规则见认证与签名，Webhook 投递重试另见Webhook 通知。