錯誤處理 - 帳獸 Zangsho

錯誤格式

當 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."
    ]
  }
}

常見驗證錯誤

欄位	錯誤訊息	說明
`email`	`The email has already been taken.`	該商家下已存在相同 email 的客戶
`order_no`	`The order no has already been taken.`	該商家下已存在相同訂單編號
`amount`	`The amount must be at least 0.`	金額不可為負數
`status`	`The selected status is invalid.`	狀態值不在允許的選項中
`billing_cycle`	`The 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();
}

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://api.zangsho.com/v1/customers', $data);

if ($response->failed()) {
    match ($response->status()) {
        401 => Log::error('認證失敗，請檢查 API Token'),
        422 => Log::error('驗證錯誤', $response->json('errors')),
        429 => Log::warning('超過頻率限制', [
            'retry_after' => $response->header('Retry-After'),
        ]),
        default => Log::error('發生錯誤', [
            'status' => $response->status(),
            'message' => $response->json('message'),
        ]),
    };
}

最佳實踐

總是檢查 HTTP 狀態碼

不要只依賴回應內容來判斷成功或失敗，務必檢查 HTTP 狀態碼。2xx 代表成功，4xx 代表客戶端錯誤，5xx 代表伺服器錯誤。

妥善處理 422 驗證錯誤

當收到 422 錯誤時，解析 errors 物件並針對各欄位顯示對應的錯誤訊息。這能幫助使用者快速修正問題。

實作指數退避重試

對於 429（頻率限制）和 5xx（伺服器錯誤），建議實作指數退避重試策略。讀取 Retry-After 標頭來決定等待時間。

記錄錯誤日誌

將 API 錯誤回應記錄到日誌中，包含請求路徑、狀態碼與錯誤訊息，方便日後排查問題。

​錯誤格式

​HTTP 狀態碼

​成功回應

​錯誤回應

​驗證錯誤（422）

​常見驗證錯誤

​錯誤處理範例

​最佳實踐