错误码

所有接口共用一套错误结构。

{
  "code": 400,
  "error": "invalid_request",
  "type": "invalid_request_error",
  "message": "订单金额必须是以最小货币单位表示的正整数",
  "param": "amount",
  "doc_url": "https://kukopay.com/docs/api/errors",
  "request_id": "req_9f2c1a7b4e8d0356c1ab77de90f4b215"
}

request_id

每一个响应——无论成功还是失败——都会在响应体的 request_id 字段和 X-Request-Id 响应头中返回同一个值，它与平台侧日志一一对应。

request_id 始终由平台签发，不接受请求方传入，所以两次不同的调用一定拿到不同的值。

错误大类

完整错误码

重试原则

• 网络超时、429、502 和 500：保留相同幂等键，指数退避后重试。
• 400、401、403：先修复参数、凭据或权限，不要原样循环重试。
• 404：确认资源标识与测试/正式环境是否一致。
• 409：重新查询订单、退款或拒付的最新状态，再决定下一步。

调用频率限制

商户 API 按商户维度限流，窗口为一分钟：

超出后返回 429 rate_limited，响应头 Retry-After 给出距离窗口重置的秒数。按这个秒数退避即可，不必自己猜。