Skip to main content
此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

​
冪等性與重試

配送標籤涉及實際的成本和物流影響。重複標籤會導致營運混亂、配送費用浪費以及庫存追蹤錯誤。Flex Forward API 內建冪等性來防止此問題。

​
冪等性的運作方式

POST /labels 端點使用 idempotencyKey 欄位來確保每個標籤建立請求只會被處理一次。 第一次請求 — API 建立標籤並回傳 HTTP 201：
201 Created
重放的請求 — 相同的 idempotencyKey 會回傳原始結果（HTTP 200），而不會建立新標籤：
200 OK（冪等重放）
冪等性金鑰的範圍限於您的 API 帳戶。不同帳戶可以使用相同的金鑰而不會衝突。

​
選擇冪等性金鑰

金鑰應該唯一識別預期的標籤建立。良好的模式：
重試相同的邏輯請求時，絕不要產生新的 idempotencyKey。請重複使用原始金鑰，以便 API 能偵測重複。
400 驗證錯誤後，由於未建立標籤，可以重複使用相同的 idempotencyKey。修正請求後使用相同金鑰重試。

​
重試策略

對於暫時性失敗（HTTP 500、502 或網路逾時），請使用指數退避重試：
1

設定請求逾時

為 HTTP 請求設定合理的逾時時間（例如 30 秒）。
2

失敗時等待再重試

使用指數退避：1 秒、2 秒、4 秒、8 秒。
3

重複使用相同的冪等性金鑰

始終使用與原始請求相同的 idempotencyKey 重試。即使原始請求已成功但回應遺失，也能確保不會建立重複標籤。
4

限制重試次數

在 3–5 次重試後停止。如果請求仍然失敗，記錄錯誤並升級調查。

​
各端點的冪等性

​
失敗場景

標籤可能已建立也可能未建立。使用相同的 idempotencyKey 重試。如果標籤已建立，API 會回傳 HTTP 200 和原始結果。如果未建立，API 會建立標籤並回傳 HTTP 201。
暫時性伺服器錯誤。使用相同的 idempotencyKey 並以退避策略重試。
物流業者服務回傳錯誤。標籤以 status: failed 保存。重試前請檢查錯誤訊息 — 部分物流業者錯誤需要修改請求（如無效地址）。對於暫時性的物流業者問題，使用相同的 idempotencyKey 重試。
請求無效。未修正請求前請勿重試。由於未建立標籤，修正請求本文後可以重複使用相同的 idempotencyKey。