錯誤處理

所有 API 錯誤都採用一致的格式。以下說明如何妥善處理。

錯誤回應格式

發生錯誤時，API 會回傳以下結構的 JSON 物件：

json

{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

狀態碼	錯誤	原因與解決方式
`400`	錯誤的請求	JSON 格式錯誤或缺少必填欄位。請檢查請求內容。
`401`	未經授權	缺少 API 金鑰或金鑰無效。請檢查您的`Authorization`標頭。
`402`	需要付款	點數不足。請購買更多點數，或等待每日額度重設。
`422`	驗證錯誤	電子郵件地址格式無效。請檢查您送出的值。
`429`	請求過多	已超過速率限制。請查看`Retry-After`標頭並稍候再試。
`500`	伺服器內部錯誤	我們這邊出了點問題。請過幾秒再試一次。聯絡客服（若持續失敗）。

json

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

修正方式：請確認您的Authorization標頭格式正確，應為Bearer YOUR_API_KEY。並在儀表板中確認您的金鑰。

json

{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

修正方式：請確認電子郵件值的格式有效（例如user@example.com）。送出前先清理輸入資料。

json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

修正方式：請等待以下欄位指定的秒數：retry_after之後再重試。請參閱速率限制 →