# 回應格式

所有成功的回應都採用同一個信封結構，讓你用一致的方式解析每個端點的結果。

## 成功信封

```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" %}
請只依賴上述「有出現才解析」的原則撰寫客戶端：當某欄位不存在時，視為該資訊不適用，而非錯誤。
{% 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         |
| `Retry-After`        | 限流（429）時，建議幾秒後重試     |

## 下一步

{% 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 %}


---

# Agent Instructions: 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/response-format.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.