限流

說明 API key、endpoint 與方案層級的限流規則，以及超量時的回應方式。

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

限流維度

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

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

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

超量時會發生什麼

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

Reject（直接拒絕）

立即回傳 429 rate_limited，並附上 Retry-After header 告訴你建議幾秒後重試。

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

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

Wait（排隊等待）

若 endpoint 或方案支援排隊模式，請求可在短時間內進入等待佇列，待額度釋放後繼續處理。

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

最佳實務

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

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

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

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

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

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

下一步

Credit 計費