跳轉到主要內容
啟潤支付使用標準 HTTP 狀態碼來表示 API 請求的成功或失敗。

​
HTTP 狀態碼

狀態碼描述
200成功 — 請求已成功處理
201已建立 — 資源建立成功
400錯誤請求 — 參數無效
401未認證 — 缺少或無效的 API 密鑰
403禁止存取 — 權限不足
404未找到 — 資源不存在
429請求過多 — 超出頻率限制
500伺服器內部錯誤 — 我們這邊出了問題

​
錯誤回應格式

發生錯誤時，回應本體包含以下 JSON 結構： 
{
  "code": 400,
  "message": "Bad Request",
  "error": {
    "field": "productId",
    "reason": "Product ID is required"
  }
}
欄位類型描述
codeintegerHTTP 狀態碼
messagestring人類可讀的錯誤訊息
error.fieldstring導致錯誤的參數（如適用）
error.reasonstring詳細的錯誤說明
error 物件僅在驗證錯誤（400）時出現。其他錯誤類型只包含 code 和 message。

​
常見錯誤

​
400 錯誤請求

請求本體或參數無效時返回。 
{
  "code": 400,
  "message": "Bad Request",
  "error": {
    "field": "price",
    "reason": "Price must be at least 0.01"
  }
}

​
401 未認證

API 密鑰缺失或無效時返回。 
{
  "code": 401,
  "message": "Unauthorized"
}

​
404 未找到

請求的資源不存在時返回。 
{
  "code": 404,
  "message": "Not Found"
}

​
429 請求過多

超過 API 頻率限制（每分鐘 100 次請求）時返回。 
{
  "code": 429,
  "message": "Too Many Requests"
}
在你的整合中實現指數退避策略，以優雅地處理頻率限制。

​
成功回應格式

成功的回應始終包含 code: 0 和 message: "success"： 
{
  "code": 0,
  "message": "success",
  "data": {
    // 回應資料
  }
}
對於分頁介面，data 欄位包含 items 和 pagination： 
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 42,
      "totalPages": 3
    }
  }
}