REST API v1 · 開發者
冪等重試
網路難免出錯:請求可能已經抵達 BotGG,回應卻沒有送回給你。會改變狀態的寫入操作都支援 Idempotency-Key 標頭,讓你可以放心重試,不會重複套用同一個變更。
開發者文件
本頁目錄
運作方式
請傳送 Idempotency-Key 標頭,內容為 1 到 100 個可列印的 ASCII 字元(最適合使用 UUID),並且在同一個變更的每次重試中使用相同的值。支援此標頭的端點,在 API 參考文件中會顯示 Idempotency-Key 標籤。
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, ... }HTTP/1.1 422 Unprocessable Entity
{ "error": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was already used with a different request" }實務做法
- 每個邏輯操作(例如每一筆錦標賽獎金發放)只產生一次金鑰,並在第一次嘗試之前就產生好。
- 如果重試可能發生在重新啟動之後,請把金鑰連同該操作一起存進你自己的資料庫。
- 遇到逾時、網路錯誤、
429、500或503時,請用相同的金鑰,原封不動地再送一次相同的請求。 - 下一個不同的操作,則使用新的金鑰。