Skip to main content

错误格式

所有错误响应遵循统一的结构:

读取 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 这类简短、易猜的键可能与另一个请求已使用的键相同。此时您收到的是那个请求的缓存响应,而不是本次调用的结果。