REST API v1 · 開發者

冪等重試

網路難免出錯:請求可能已經抵達 BotGG,回應卻沒有送回給你。會改變狀態的寫入操作都支援 Idempotency-Key 標頭,讓你可以放心重試,不會重複套用同一個變更。

開發者文件
本頁目錄

運作方式

請傳送 Idempotency-Key 標頭,內容為 1 到 100 個可列印的 ASCII 字元(最適合使用 UUID),並且在同一個變更的每次重試中使用相同的值。支援此標頭的端點,在 API 參考文件中會顯示 Idempotency-Key 標籤。

curl
curl -s -X POST https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6a2e-8d4b-4c1e-9a7f-2b3c4d5e6f70" \
  -d '{"type":"add","amount":100,"reason":"Tournament prize"}'
  • 成功的回應會依每把 API 金鑰儲存 24 小時。使用相同金鑰與相同請求重試時,會直接回傳原始回應(狀態與內容相同,另加上 Idempotent-Replayed: true 標頭),不會再次更動任何資料。
  • 相同的金鑰搭配不同的內容、成員或路徑,會失敗並回傳 422 IDEMPOTENCY_KEY_REUSED。
  • 失敗的請求(4xx 與 5xx)不會被儲存,所以你可以修正問題後,用同一個金鑰重試。
  • 兩個同時送出、使用相同金鑰的請求也是安全的:第二個會等待第一個完成,再取得它儲存的回應。
  • 如果沒有帶這個標頭,重試的請求就會被視為新的變更。
重播的回應
HTTP/1.1 201 Created
Idempotent-Replayed: true

{ "transactionId": 98765, "balance": 1350, ... }
回應 · 422
HTTP/1.1 422 Unprocessable Entity

{ "error": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was already used with a different request" }

實務做法

  1. 每個邏輯操作(例如每一筆錦標賽獎金發放)只產生一次金鑰,並在第一次嘗試之前就產生好。
  2. 如果重試可能發生在重新啟動之後,請把金鑰連同該操作一起存進你自己的資料庫。
  3. 遇到逾時、網路錯誤、429、500 或 503 時,請用相同的金鑰,原封不動地再送一次相同的請求。
  4. 下一個不同的操作,則使用新的金鑰。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。