错误格式
所有错误响应遵循统一的结构:读取 errors 数组
errors 数组按从根因到顶层调用方的顺序排列:
errors[0]— 故障的根因(对调试最有用)errors[n]— 暴露错误的顶层调用方
errors[0].message 即可获取可操作的错误描述。
HTTP 状态码
错误 layer 字段
每个错误包含一个 layer 字符串,指示系统的哪个部分产生了该错误。调试时可将 layer 值与 message 结合使用来定位根因。
常见错误场景
认证错误 (401)
- 验证您的 Merchant ID 和私钥是否正确
- 确保 SDK 初始化时使用了有效的凭证
- 检查您的私钥是否与已注册的公钥匹配
验证错误 (400)
- 检查必填字段是否已提供
- 验证字段值的格式和约束
- 确保金额为显示格式字符串(例如 “29.00”)
权限错误 (403)
- 验证 API Key 具有所需的权限
- 确保用户属于正确的门店
幂等冲突 (409)
- 等待原始请求完成
- 使用不同的
X-Idempotency-Key发起新请求
在代码中处理错误
TypeScript SDK
重试策略
对以下状态码使用指数退避重试:- 429 — 频率限制(如有
Retry-After请求头则遵循) - 500 — 内部服务器错误
- 502 — 网关错误
不要重试
400、401、403 或 404 错误。这些错误表示请求本身存在问题,需要修正。幂等性保障安全重试
写操作带上X-Idempotency-Key 时才能安全重试而不创建重复记录。
不发键就没有任何去重。 SDK 过去会用
merchantId + 路径 + 请求体 生成键,现在任何凭证下都不再生成 —— 因此默认情况下,写操作在超时后重试会执行两次。经 SDK 调用时按调用传键(TypeScript 与 @waffo/pancake-nextjs 用 { idempotencyKey },Go 用 pancake.WithIdempotencyKey(key));直连 REST 则自己设置该请求头。下面的要求对两者都适用。- 幂等键缓存 24 小时
- 使用相同的键将返回缓存的响应
- 如果原始请求仍在处理中,返回
409 Conflict
幂等键要求
幂等键本身就是请求的完整缓存标识,因此唯一性是需要重点规划的要求。请在键中嵌入您的
merchantId 以及高熵成分(例如 UUID),如 MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67。不要用请求体哈希当键:两次本应各自生效的相同写操作会撞成同一个键,第二次只会重放第一次的响应。
order-abc-123 这类简短、易猜的键可能与另一个请求已使用的键相同。此时您收到的是那个请求的缓存响应,而不是本次调用的结果。