> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 速率限制

> 理解讀取、寫入與執行請求的速率限制回應。

<Note>
  **私人測試版。** 新組織預設已啟用。組織管理員仍須在 Brightalk 設定中建立具權限範圍的 API 金鑰，請求才能通過驗證。可用範圍與限制以本文件和 OpenAPI 契約為準。
</Note>

Brightalk 會對每個組織套用速率限制，也可能對個別金鑰套用更嚴格的限制。有效限制是目前請求所適用的較低配額。

## 速率限制配額群組

每個操作會使用三個獨立配額群組的其中一個。目前請求以回應標頭為準。

| 配額群組        | 操作範例                                     |
| ----------- | ---------------------------------------- |
| `read`      | 列出及查詢資源                                  |
| `write`     | 寫入聯絡人；建立批次；取消通話；暫停或取消批次；取消 Automation 執行 |
| `execution` | 建立通話；啟動或繼續批次；建立 Automation 執行            |

取消及暫停操作使用 `write`，不是 `execution`。已接受的執行請求所啟動的電話工作，不會再使用另一筆 HTTP 請求配額。

## 讀取標頭

| 標頭                    | 意義                                                     |
| --------------------- | ------------------------------------------------------ |
| `RateLimit-Limit`     | 所選配額群組的有效配額                                            |
| `RateLimit-Remaining` | 該配額群組剩餘的非負請求次數                                         |
| `RateLimit-Reset`     | 從產生回應到重設配額的非負整數差值秒數（delta-seconds）；絕不是 Unix epoch 時間戳記 |
| `Retry-After`         | 重試遭拒請求前應等待的非負整數差值秒數（delta-seconds）                     |

請使用這些值，不要假設每個組織或金鑰都採用相同配額。

## 處理 429 回應

配額用盡時會傳回 `429 rate_limit_exceeded`。請至少等待數字 `Retry-After` 指定的時間、加入隨機延遲，並僅在操作可安全重試時重送。重試同一個具冪等性的邏輯動作時，應保留相同的 `Idempotency-Key`。

## 區分容量與 HTTP 速率限制

電話並行容量是另一種控制。容量暫時已滿時，已接受的工作會保持 `queued`；不會變成 `429`，也不會遭丟棄。請查詢 API 資源，並將排隊視為生命週期狀態，而非請求節流訊號。