錯誤碼對照表

每個 API 端點共用同一組錯誤碼。查 HTTP status 或 error.code，看常見原因、能不能重試、該怎麼處理。

每個錯誤回應都長這樣：{ ok: false, requestId, correlationId, error: { code, message, nextAction } }。程式邏輯請判斷 error.code（穩定字串），message／nextAction 只是給人看的說明，可能會調整措辭。完整信封格式見 API 基礎規則。

驗證與請求格式

HTTP	code	常見原因	可重試？
400	`VALIDATION_ERROR`	欄位缺漏、型別錯誤、超出允許範圍（例如金額不是整數）	修正欄位後可以重送，原樣重試沒有用
400	`IDEMPOTENCY_KEY_REQUIRED`	財務操作（付款/退款/結帳）沒有帶 `Idempotency-Key` 標頭	加上標頭後重送

身分與權限

HTTP	code	常見原因	可重試？
401	`UNAUTHENTICATED`	沒帶 `Authorization: Bearer`，或金鑰不存在／已撤銷	換一把有效金鑰後重送；原樣重試沒有用
401	`TOKEN_EXPIRED`	登入型 API 的 access token 已過期（15 分鐘）	用 refreshToken 呼叫對應的 `*/Refresh` 換發後重送
401	`INVALID_TOKEN`	access token 格式或簽章不正確	重新登入取得新的 token
401	`INVALID_REFRESH_TOKEN`	refreshToken 已使用過、已登出或已過期	重新登入；refreshToken 每次換發都會輪替，舊的不能再用
403	`WRONG_TOKEN_TYPE`	用錯類型的 token（例如商家 token 呼叫 `Admin*`）	改用該 API 對應的登入身分
404	`ROUTE_NOT_FOUND`	路徑不存在（例如還在用舊的 `/v1/...`）	對照 `GET /api/OpenApi` 改用正確路徑
403	`SCOPE_DENIED`	金鑰沒有這個操作需要的 scope	到後台建立一把有正確 scope 的金鑰
403	`SCOPE_DISABLED`	要求的 scope（例如 `payouts:*`）尚未對外開放	不可重試——這個能力還沒上線，見 Sandbox 與正式環境
403	`WORKSPACE_ACCESS_DENIED`	金鑰只能存取建立它的 workspace，請求卻帶了別的 workspace id	確認 `x-workspace-id` 或改用對的金鑰；不可重試
403	`ENVIRONMENT_DENIED`	請求指定了 sandbox 以外的環境（正式環境尚未開放）	改用 sandbox；不可重試

資源狀態

HTTP	code	常見原因	可重試？
404	`NOT_FOUND`	ID 打錯、資源屬於別的 workspace、或已被刪除	確認 ID 後重送；原樣重試沒有用
409	`CONFLICT`	跟現有資料衝突（例如唯一值重複）	調整欄位後重送

流量限制

HTTP	code	常見原因	可重試？
429	`RATE_LIMITED`	超過該把金鑰的請求配額（預設每 60 秒 120 次）	可重試——依 `Retry-After` 標頭的秒數等待後再送，見 API 基礎規則

伺服器錯誤

HTTP	code	常見原因	可重試？
500	`INTERNAL_ERROR`	非預期的伺服器錯誤	可以帶退避（backoff）重試一兩次；如果持續發生，帶著 `requestId` 聯絡支援

付款相關的「非錯誤」狀態（例如 unknown 待對帳、退款前置檢查回傳的 PAYMENT_UNKNOWN_NEEDS_RECONCILE）不是 HTTP 錯誤，而是 200 回應裡的業務欄位——這些請看退款與 Idempotency，不在這張表裡。

什麼時候該聯絡支援：如果同一個 requestId 對應的請求重試過依然是 500 INTERNAL_ERROR，或收到一個這張表沒列出的 error.code，把 requestId／correlationId 一起附上再聯絡，會比較好排查。

← Webhooks 版本策略與更新紀錄 →