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 — 网关错误
不要重试 400401403404 错误。这些错误表示请求本身存在问题,需要修正。

幂等性保障安全重试

使用 X-Idempotency-Key 请求头安全地重试写操作,避免创建重复记录:
  • 幂等键缓存 24 小时
  • 使用相同的键将返回缓存的响应
  • 如果原始请求仍在处理中,返回 409 Conflict

幂等键要求

幂等键本身就是请求的完整缓存标识,因此唯一性是需要重点规划的要求。两种做法:
  1. 由 SDK 生成(推荐)。 TypeScript SDK 将幂等键计算为 merchantId + 路径 + 请求体 的确定性哈希,因此天然做到每个请求唯一。
  2. 自行构造。 在键中嵌入您的 merchantId 以及高熵成分(例如 UUID),如 MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67
order-abc-123 这类简短、易猜的键可能与另一个请求已使用的键相同。此时您收到的是那个请求的缓存响应,而不是本次调用的结果。