> 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/he-xin-gai-nian/errors.md).

# 錯誤處理

所有錯誤都回傳一致的結構與一個**機器可讀的錯誤碼**，讓你能用程式判斷該如何反應，而不必只靠 HTTP 狀態碼。

## 錯誤信封

```json
{
  "error": {
    "code": "insufficient_credit",
    "message": "insufficient credit: required 5, remaining 2"
  }
}
```

* **`code`** — 穩定的字串代碼，請用它做程式化分支。
* **`message`** — 人類可讀的說明，僅供顯示／記錄，內容可能調整，**請勿**拿來做邏輯判斷。

{% hint style="info" %}
基於安全考量，`500 internal_error` 對外只回傳通用訊息，細節僅記錄在伺服器端。回報時請附上 `X-Request-Id`。
{% endhint %}

## 錯誤碼一覽

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

## 建議的重試策略

* **可安全重試**：`429`、`502`、`503`。對 `429` 請遵守 `Retry-After`；其餘建議採用指數退避（exponential backoff）。
* **不要盲目重試**：`400`、`401`、`403`、`404` 通常是請求本身的問題，重試前先修正。
* **計費例外**：`402` 在加值前重試只會再次失敗。

{% hint style="success" %}
**好消息：** 因為 credit **只在成功（2xx）時扣除**，任何錯誤回應都不會扣你的點數。
{% endhint %}

## 下一步

{% content-ref url="/pages/hauJglYxlKcGMt6ydPim" %}
[限流](/documentation/he-xin-gai-nian/rate-limiting.md)
{% endcontent-ref %}

{% content-ref url="/pages/yecpZZZrz03pEiGYQiNa" %}
[錯誤碼](/documentation/api-can-kao/error-codes.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/he-xin-gai-nian/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.