# 錯誤與重試

安全恢復失敗請求，避免重複購買。

## 檢視回應

錯誤回應包含 `code` 和 `request_id`，請保留用於排查。`202` 表示已受理，請使用回傳的編號查詢完成狀態。

| 狀態碼 | 建議操作 |
| --- | --- |
| `401` | 檢查金鑰是否有效、已過期或被撤銷 |
| `403` | 檢查存取權限、範圍、允許的 IP 和支出限制 |
| `404` | 檢查編號及其是否屬於當前工作空間 |
| `409` | 先重新整理資源或報價，再決定下一步 |
| `422` | 根據錯誤程式碼修正請求欄位 |
| `429` | 按 `Retry-After` 等待後再請求 |
| `5xx` 或無回應 | 重試寫入前先檢查原操作 |

## 重試同一次操作

對於需要 `Idempotency-Key` 的端點，為新操作產生一次識別碼，並與原請求體一起儲存。重試時複用兩者。成功操作的重複請求會回傳原結果，不會再次從錢包扣款。

不要因為超時而產生新識別碼。同一識別碼配合不同請求體會產生衝突。是否需要該請求頭，請檢視[API 參考](/zh-tw/docs/api)。

## 流量購買需要處理

`DYNAMIC_GRANT_FAILED` 或 `DYNAMIC_GRANT_UNKNOWN` 可能包含購買記錄。讀取 `GET /dynamic/purchases/{id}`，並向支援提供購買編號。使用原識別碼重複購買請求不會重新啟動啟用。

支援人員可以稽覈購買。客戶 API 金鑰不能自行重試啟用，也不能取消並退款。

## 遵守請求限額

每個金鑰每分鐘最多 120 次請求。遇到 `429` 請遵循 `Retry-After`，狀態不變時適當降低輪詢頻率。支援的事件可以用 Webhook 替代頻繁輪詢。

## 保留數值精度

金額是人民幣分的整數字串，請使用整數運算或十進位制庫。時間戳使用 UTC。餘額不可用時為 `null`。請逐頁讀取分頁列表，取得完整結果。