錯誤碼與重試

所有錯誤碼、對應 HTTP 狀態與處理建議。

所有錯誤回應皆採用一致結構，並回傳可供程式判斷的錯誤碼。請以 error.code 作為邏輯判斷依據；error.message 僅供顯示與紀錄，不建議作為程式分支條件。

HTTP	code	意義	處理方式
400	bad_request	參數或格式錯誤	修正請求後重送
401	unauthorized	缺少或無效的 API key	檢查 X-API-Key
402	insufficient_credit	credit 餘額不足	加值後重試
403	forbidden	無權限（如 key 已停用）	聯絡管理員
404	not_found	資源不存在	檢查路徑或 ID
429	rate_limited	觸發限流	依 Retry-After 重試
500	internal_error	內部錯誤	附 X-Request-Id 回報
502	upstream_error	後端服務異常	退避後重試
503	service_unavailable	暫時無法處理（如佇列已滿）	稍後重試

錯誤回應 header

錯誤	header	意義
429 rate_limited	Retry-After	建議等待秒數後重試

範例

以下為觸發限流時的錯誤回應範例：

{
  "error": {
    "code": "rate_limited",
    "message": "rate limited, retry after 3s"
  }
}

延伸閱讀：錯誤處理。