Idempotency-Key,Brightalk 就能辨識這是同一個動作,並傳回原本的結果。
三個使用原則
- 一個動作,一把金鑰。 第一次送出請求前,先產生不重複且非機密的值。
- 同一個動作,沿用同一把金鑰。 在 24 小時內,若請求逾時、連線失敗,或回應明確要求重試(例如包含
Retry-After),請使用相同的 HTTP 方法、路徑、API 版本、語意相同的請求內容與金鑰重送。 - 動作或內容改變,就換新金鑰。 若 API 版本或請求內容不同,或您確實要再建立一通電話、另一個批次或另一次自動化執行,請使用新的金鑰。
Content-Type 標頭。
order-8f4c2-call-1 與這次業務動作一起保存。它不是驗證金鑰,但仍不可包含電話號碼、聯絡人資料或其他機密。
超過 24 小時後,請勿假設舊的冪等性宣告仍能防止重複執行。再次送出前,請先確認原本的動作是否已經執行。
哪些操作一定要使用
只有以下四個操作強制要求此標頭:
省略標頭會傳回
400 idempotency_key_required。
哪些操作可選擇使用
狀態控制操作可選用此標頭;加入標頭後,即可重播已完成的結果:Brightalk 會傳回什麼
請等待
Retry-After 指定的時間後,再重試處理中的請求。驗證失敗不會儲存成已完成的冪等結果。
進階細節
冪等性宣告會保留 24 小時,其適用範圍由組織、API 金鑰類別、API 版本、HTTP 方法與正規化路徑共同決定。從一把bt_live_ 金鑰輪替到另一把金鑰,不會重設相同金鑰類別的宣告;輪替後重試同一邏輯請求時,請沿用原本的冪等性金鑰。