Skip to main content
即使您的伺服器逾時,請求仍可能已成功。若改用新的冪等性金鑰重試,Brightalk 可能會重複建立同一通電話、同一個批次或同一次自動化執行。沿用相同的 Idempotency-Key,Brightalk 就能辨識這是同一個動作,並傳回原本的結果。

三個使用原則

  1. 一個動作,一把金鑰。 第一次送出請求前,先產生不重複且非機密的值。
  2. 同一個動作,沿用同一把金鑰。 在 24 小時內,若請求逾時、連線失敗,或回應明確要求重試(例如包含 Retry-After),請使用相同的 HTTP 方法、路徑、API 版本、語意相同的請求內容與金鑰重送。
  3. 動作或內容改變,就換新金鑰。 若 API 版本或請求內容不同,或您確實要再建立一通電話、另一個批次或另一次自動化執行,請使用新的金鑰。
以下僅節錄標頭,刻意省略必要的 JSON 請求內容與 Content-Type 標頭。
請將 order-8f4c2-call-1 與這次業務動作一起保存。它不是驗證金鑰,但仍不可包含電話號碼、聯絡人資料或其他機密。 超過 24 小時後,請勿假設舊的冪等性宣告仍能防止重複執行。再次送出前,請先確認原本的動作是否已經執行。

哪些操作一定要使用

只有以下四個操作強制要求此標頭: 省略標頭會傳回 400 idempotency_key_required

哪些操作可選擇使用

狀態控制操作可選用此標頭;加入標頭後,即可重播已完成的結果:

Brightalk 會傳回什麼

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

進階細節

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