> 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/response-format.md).

# 回應格式

所有 API 模組皆採用一致的 response envelope。成功回應以 data 與 meta 回傳結果與請求資訊；錯誤回應以 error 回傳錯誤碼、訊息與追蹤資訊，方便工程串接、除錯、稽核與對帳。

## 成功信封

```json
{
  "data": <實際資料>,
  "meta": {
    "request_id": "9b1c2d3e-...",
    "pagination": { "limit": 20, "offset": 0, "total": 134 },
    "credit_cost": 5,
    "credit_remaining": 9995
  }
}
```

* **`data`** — 實際的業務資料。可能是物件、陣列，或列表型端點的項目集合。
* **`meta`** — 與本次請求有關的中繼資訊。欄位皆為選用，沒有就不會出現：

| 欄位                 | 何時出現  | 意義                                                       |
| ------------------ | ----- | -------------------------------------------------------- |
| `request_id`       | 一律    | 本次請求的追蹤碼，同 `X-Request-Id`                                |
| `pagination`       | 列表型端點 | 分頁狀態，見[分頁](/documentation/he-xin-gai-nian/pagination.md) |
| `credit_cost`      | 有計費時  | 本次扣除的 credit                                             |
| `credit_remaining` | 有計費時  | 扣除後的剩餘餘額                                                 |

{% hint style="info" %}
客戶端應依「欄位存在才解析」的原則處理 meta。某些欄位只會在特定 endpoint、計費方案或列表型查詢中出現；欄位不存在不代表錯誤。
{% endhint %}

## 錯誤信封

錯誤一律回傳對稱的結構，詳見[錯誤處理](/documentation/he-xin-gai-nian/errors.md)：

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

## 回應 header

| Header               | 說明                            |
| -------------------- | ----------------------------- |
| `X-Request-Id`       | 請求追蹤碼（可自帶沿用）                  |
| `X-Credit-Cost`      | 本次請求扣除的 credit，僅成功且需計費時出現     |
| `X-Credit-Remaining` | 扣點後剩餘 credit，僅適用於 Credit 方案   |
| `Retry-After`        | 遇到 429 rate limit 時，建議等待幾秒後重試 |

## 下一步

{% content-ref url="/pages/BBN0nBFpnfmeQEccdirr" %}
[錯誤處理](/documentation/he-xin-gai-nian/errors.md)
{% endcontent-ref %}

{% content-ref url="/pages/JTozQ5Gb9ly2bavrljBP" %}
[分頁](/documentation/he-xin-gai-nian/pagination.md)
{% endcontent-ref %}