> 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/rate-limiting.md).

# 限流

為確保服務穩定、公平使用與企業級用量控管，BCS Intelligence API 會依照 API key、endpoint、客戶方案與請求頻率套用限流規則。

## 限流維度

限流以「API key + endpoint」為主要單位。不同 API key、不同 endpoint 可依方案設定不同額度；高頻查詢、批次查詢、即時串流與 webhook 類功能可能採用不同限流規則。

額度由兩個參數決定，依你的方案設定：

| 參數        | 意義           |
| --------- | ------------ |
| **RPS**   | 每秒可穩定處理的請求數  |
| **Burst** | 短時間內可累積的突發容量 |

## 超量時會發生什麼

當請求超過額度時，系統會依客戶方案與 endpoint 設定採用以下其中一種行為：

{% tabs %}
{% tab title="Reject（直接拒絕）" %}
立即回傳 `429 rate_limited`，並附上 `Retry-After` header 告訴你建議幾秒後重試。

```
HTTP/1.1 429 Too Many Requests
Retry-After: 3
```

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

{% endtab %}

{% tab title="Wait（排隊等待）" %}
若 endpoint 或方案支援排隊模式，請求可在短時間內進入等待佇列，待額度釋放後繼續處理。

若等待佇列已滿、等待時間過長或服務進入保護狀態，系統會回傳 `503 service_unavailable`，請稍後重試。
{% endtab %}
{% endtabs %}

## 最佳實務

• 遵守 Retry-After：收到 429 時，請等待指定秒數後再重試，不要立即連續重打。

• 採用指數退避：對 429、502、503 使用 exponential backoff，避免短時間大量重試造成雪崩。

• 控制並發數：在客戶端設定合理的 concurrency 上限，避免瞬間打滿 Burst 額度。

• 分散批次任務：大量地址、交易或資金流查詢應拆成批次，平滑送出請求。

• 記錄 request\_id：若發生 429、503 或非預期錯誤，請保留 meta.request\_id 或 X-Request-Id，方便追蹤。

{% hint style="info" %}
需要更高額度？可依使用場景申請更高 RPS、Burst、批次查詢或即時串流方案。量化、高頻監控與大型批次查詢建議預先評估流量模型。
{% endhint %}

## 下一步

{% content-ref url="/pages/pdZr13kdI275d1FWwSKR" %}
[Credit 計費](/documentation/he-xin-gai-nian/credit-billing.md)
{% endcontent-ref %}