错误格式
所有错误响应遵循统一的结构:读取 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 请求头安全地重试写操作,避免创建重复记录:
- 幂等键缓存 24 小时
- 使用相同的键将返回缓存的响应
- 如果原始请求仍在处理中,返回
409 Conflict
幂等键要求
幂等键本身就是请求的完整缓存标识,因此唯一性是需要重点规划的要求。两种做法:
- 由 SDK 生成(推荐)。 TypeScript SDK 将幂等键计算为
merchantId+ 路径 + 请求体 的确定性哈希,因此天然做到每个请求唯一。 - 自行构造。 在键中嵌入您的
merchantId以及高熵成分(例如 UUID),如MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67。
order-abc-123 这类简短、易猜的键可能与另一个请求已使用的键相同。此时您收到的是那个请求的缓存响应,而不是本次调用的结果。