# 限流

為確保服務穩定與公平使用，Blockchain Atlantis 對每把 API key 進行限流。

## 限流維度

限流以 **「API key + 端點」** 為單位。也就是說，同一把 key 對不同端點各有獨立的額度，彼此不互相排擠。

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

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

## 超量時會發生什麼

當你超出額度，依方案設定有兩種行為：

{% 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（排隊等待）" %}
請求會在容量內**短暫排隊**，等到有額度時自動放行，你不需重送。

若等待佇列已滿（伺服器過載保護），則回傳 `503 service_unavailable`，請稍後再試。
{% endtab %}
{% endtabs %}

## 最佳實務

* **遵守 `Retry-After`**：收到 `429` 時，等待指定秒數再重試，而不是立刻重打。
* **採用指數退避**：對 `429`／`503` 以漸增的間隔重試，避免雪崩。
* **控制併發**：在客戶端設定合理的併發上限，平滑送出請求。

{% hint style="info" %}
需要更高的額度嗎？請聯絡你的客戶經理調整方案，或請管理員為該 key 套用更高 RPS／Burst 的方案。
{% endhint %}

## 下一步

{% content-ref url="/pages/pdZr13kdI275d1FWwSKR" %}
[Credit 計費](/documentation/he-xin-gai-nian/credit-billing.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/rate-limiting.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.