状态与错误码

统一响应

成功：

json

{ "ok": true }

失败：

json

{
  "ok": false,
  "error_code": "insufficient_stock",
  "error_message": "insufficient stock"
}

业务失败可能使用非 2xx，也可能像 payment_failed 一样返回 HTTP 200。因此客户端必须同时检查 HTTP 状态码和 JSON 中的 ok。

订单状态

状态	说明	建议处理
`pending_payment`	待支付	继续等待
`paid`	已支付，等待交付	继续等待
`fulfilling`	正在履约	继续等待
`partially_delivered`	部分交付	记录状态，继续等待
`delivered`	已交付	读取 `fulfillment`
`completed`	已完成	读取并保存 `fulfillment`
`canceled`	已取消	停止等待并进入取消流程

鉴权错误

错误码	说明
`missing_auth_headers`	缺少签名请求头
`invalid_timestamp`	时间戳格式错误
`timestamp_expired`	时间偏差超过约 ±60 秒
`invalid_signature`	签名错误
`invalid_api_key`	API Key 无效或被禁用
`user_disabled`	所属用户被禁用

业务错误

错误码	HTTP	说明
`bad_request`	400	参数无效
`invalid_callback_url`	400	回调地址非法
`sku_unavailable`	400	SKU 不可用
`product_unavailable`	400	商品不可用
`product_not_found`	404	商品不存在
`order_not_found`	404	订单不存在
`insufficient_balance`	402	钱包余额不足
`insufficient_stock`	409	库存不足
`cancel_not_allowed`	409	订单不可取消
`payment_failed`	200	钱包支付失败，`ok: false`
`internal_error`	500	服务端内部错误

重试策略

GET 查询可重试，建议退避间隔 1s → 2s → 4s，并设置最大等待时间。
创建订单响应不确定时不要直接自动重试，避免重复购买；应先人工确认订单结果。
参数、余额、库存和签名错误不应盲目重试。
记录 error_code、HTTP 状态码和 order_id，但不要记录 Secret。