> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/api-can-kao/error-codes.md).

# 錯誤碼與重試

所有錯誤回應皆採用一致結構，並回傳可供程式判斷的錯誤碼。請以 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` | 建議等待秒數後重試 |

## 範例

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

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

延伸閱讀：[錯誤處理](/documentation/he-xin-gai-nian/errors.md)。