> ## 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.

# 冪等性

> 以 Idempotency-Key 安全地重試支援的寫入操作。

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

冪等性可避免網路重試建立重複的外部工作。請傳送由呼叫端產生、且非機密的 `Idempotency-Key`，並將它與同一個邏輯請求一併保存。

## 必要操作

只有以下四個操作強制要求此標頭：

| 操作               | 路徑                               |
| ---------------- | -------------------------------- |
| 建立通話             | `POST /calls`                    |
| 建立批次             | `POST /batches`                  |
| 啟動批次             | `POST /batches/{batch_id}/start` |
| 建立 Automation 執行 | `POST /automation-runs`          |

省略標頭會傳回 `400 idempotency_key_required`。

## 選用操作

狀態機控制可選用此標頭；加入標頭後，即可重播已完成的結果：

| 操作               | 路徑                                      |
| ---------------- | --------------------------------------- |
| 取消通話             | `POST /calls/{call_id}/cancel`          |
| 暫停批次             | `POST /batches/{batch_id}/pause`        |
| 繼續批次             | `POST /batches/{batch_id}/resume`       |
| 取消批次             | `POST /batches/{batch_id}/cancel`       |
| 取消 Automation 執行 | `POST /automation-runs/{run_id}/cancel` |

## 適用範圍與保留期間

冪等性宣告會保留 24 小時，其適用範圍由組織、API 金鑰類別、API 版本、HTTP 方法與正規化路徑共同決定。從一把 `bt_live_` 金鑰輪替到另一把金鑰，不會重設相同金鑰類別的宣告；輪替後重試同一邏輯請求時，請沿用原本的冪等性金鑰。

每個邏輯動作都應使用不重複且不透明的值。此金鑰不是驗證金鑰，不得包含電話號碼、聯絡人資料或其他敏感資訊。

## 結果重播與衝突行為

| 情況              | 結果                                                                       |
| --------------- | ------------------------------------------------------------------------ |
| 相同金鑰與語意相同的請求內容  | 傳回原始 HTTP 狀態與回應；已完成的結果重播包含 `Idempotency-Replayed: true`                  |
| 相同金鑰與不同請求內容     | `409 idempotency_conflict`                                               |
| 原始請求仍在處理時使用相同金鑰 | `409 idempotency_in_progress`，並包含以差值秒數（delta-seconds）表示的數字 `Retry-After` |

請等待 `Retry-After` 指定的時間後，再重試處理中的請求。驗證失敗不會儲存成已完成的冪等結果。