請求失敗怎麼辦

常見錯誤的原因與排解。

請求失敗時，先看回應的 error.code，再對照下表處理。回報問題時，請附上回應 header 的 X-Request-Id。

401 unauthorized

• 確認有帶 X-API-Key header，且值正確無多餘空白。

• 確認該 key 未被撤銷。

• 為避免洩漏 key 是否存在，查無此 key 與已撤銷都回同樣的 401。

403 forbidden

key 有效但被停用（例如欠費）。請聯絡管理員恢復或加值。

402 insufficient_credit

credit 餘額不足。請管理員加值後重試。注意：加值前重試只會再次失敗。

429 rate_limited

觸發限流。請依回應的 Retry-After（秒）等待後再試，並在客戶端採用指數退避，避免立即重打。

400 bad_request

請求參數或格式有誤。常見原因：limit 超過 1000、JSON 格式錯誤、缺少必填欄位、target_url 未以 http(s):// 開頭。修正後重送。

404 not_found

資源不存在。檢查路徑與 ID；注意 webhook 只能操作該 key 自己的訂閱。

502 / 503

後端暫時異常或服務過載。請稍後以退避策略重試。若持續發生，附 X-Request-Id 聯絡支援。

500 internal_error

非預期的內部錯誤。請附上 X-Request-Id 聯絡你的客戶經理協助定位。

記得：任何錯誤回應都不會扣 credit。