Skip to main content

​
錯誤格式

當 API 請求發生錯誤時，回應會包含 message 欄位說明錯誤原因： 
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name must be a string."]
  }
}
  • message：錯誤的概要描述
  • errors：（僅驗證錯誤時出現）各欄位的詳細錯誤訊息，以欄位名稱為 key、錯誤訊息陣列為 value

​
HTTP 狀態碼

​
成功回應

狀態碼說明
200 OK請求成功，回傳資料
201 Created資源建立成功
204 No Content刪除成功，無回傳內容

​
錯誤回應

狀態碼說明常見原因
401 Unauthorized認證失敗Token 無效、未提供或已撤銷
403 Forbidden權限不足Token 沒有對應的 ability
404 Not Found資源不存在ID 或路徑錯誤，或資源屬於其他商家
422 Unprocessable Entity驗證錯誤請求資料不符合規則
429 Too Many Requests超過頻率限制請求次數超過額度
500 Internal Server Error伺服器錯誤系統異常，請稍後重試

​
驗證錯誤（422）

驗證錯誤是最常見的錯誤類型。errors 物件會列出每個有問題的欄位： 
{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "amount": [
      "The amount must be a number.",
      "The amount must be greater than 0."
    ]
  }
}

​
常見驗證錯誤

欄位錯誤訊息說明
emailThe email has already been taken.該商家下已存在相同 email 的客戶
order_noThe order no has already been taken.該商家下已存在相同訂單編號
amountThe amount must be at least 0.金額不可為負數
statusThe selected status is invalid.狀態值不在允許的選項中
billing_cycleThe selected billing cycle is invalid.不是有效的計費週期

​
錯誤處理範例

async function createCustomer(data) {
  const response = await fetch('https://api.zangsho.com/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        console.error('認證失敗，請檢查 API Token');
        break;
      case 422:
        console.error('驗證錯誤:', error.errors);
        // 處理各欄位的錯誤訊息
        for (const [field, messages] of Object.entries(error.errors)) {
          console.error(`  ${field}: ${messages.join(', ')}`);
        }
        break;
      case 429:
        const retryAfter = response.headers.get('Retry-After');
        console.error(`超過頻率限制，請在 ${retryAfter} 秒後重試`);
        break;
      default:
        console.error('發生錯誤:', error.message);
    }

    return null;
  }

  return await response.json();
}

​
最佳實踐

不要只依賴回應內容來判斷成功或失敗，務必檢查 HTTP 狀態碼。2xx 代表成功，4xx 代表客戶端錯誤，5xx 代表伺服器錯誤。
當收到 422 錯誤時，解析 errors 物件並針對各欄位顯示對應的錯誤訊息。這能幫助使用者快速修正問題。
對於 429（頻率限制）和 5xx（伺服器錯誤），建議實作指數退避重試策略。讀取 Retry-After 標頭來決定等待時間。
將 API 錯誤回應記錄到日誌中，包含請求路徑、狀態碼與錯誤訊息，方便日後排查問題。