錯誤碼

所有接口共用一套錯誤結構。

{
  "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 給出距離窗口重置的秒數。按這個秒數退避即可，不必自己猜。