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

冪等性與重試

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

冪等性的運作方式

POST /labels 端點使用 idempotencyKey 欄位，讓標籤建立可以安全地重試。使用特定金鑰的第一次請求會嘗試建立標籤。後續使用相同金鑰和相同本文的請求會以 HTTP 200 回傳已儲存的結果。使用不同本文重複金鑰會回傳 HTTP 409，代碼為 IDEMPOTENCY_CONFLICT。 第一次請求 — API 建立標籤並回傳 HTTP 201：

curl -X POST https://api.flexforwardship.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "N-2026-05-27-TEST-03",
    "courier": "yunexpress",
    ...
  }'

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

重放的請求 — 相同的 idempotencyKey 和本文會回傳原始結果（HTTP 200），而不會建立新標籤：

200 OK（冪等重放）

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

冪等性金鑰的範圍限於您的 API 帳戶。不同帳戶可以使用相同的金鑰而不會衝突。金鑰不會過期。重試時請保持本文不變。若收到 IDEMPOTENCY_CONFLICT，請用原本文取得已儲存的結果，或為修改後的請求使用新金鑰。即使只變更 customerOrderNumber 而保留相同金鑰，仍會造成衝突。較舊的標籤或其他工作流程建立的標籤可能沒有儲存本文指紋；這些記錄即使本文不同，也會維持原有的重放行為。請勿依賴衝突偵測來驗證舊標籤的細節。

絕不要同時送出兩個使用相同 idempotencyKey 的請求。請先送出一個請求，等待其回應，僅在必要時再以相同金鑰重試。使用相同金鑰的同時請求不會被去重複，並可能以 HTTP 500 失敗。

選擇冪等性金鑰

金鑰應該唯一識別預期的標籤建立。良好的模式：

模式	範例	使用場景
訂單 ID	`N-2026-05-27-TEST-03`	每個訂單一個標籤
訂單 + 序號	`N-2026-05-27-TEST-03-1`	每個訂單多個標籤
UUID	`f47ac10b-58cc-4372-a567-0e02b2c3d479`	通用
訂單 + 嘗試次數	`N-2026-05-27-TEST-03-2`	失敗標籤後的重試（見下方）

逾時或暫時性伺服器錯誤時，請重複使用原始 idempotencyKey 和未修改的本文。修改本文時必須使用新金鑰。物流業者端失敗的標籤（HTTP 502）請參閱「重試失敗的標籤」。

400 驗證錯誤後，由於未建立標籤，可以重複使用相同的 idempotencyKey。修正請求後使用相同金鑰重試。

重試策略

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

設定請求逾時

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

失敗時等待再重試

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

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

使用與原始請求相同的 idempotencyKey 和未修改的本文重試。即使原始請求已成功但回應遺失，也能取得已儲存的結果。

限制重試次數

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

嘗試 1: POST /labels → 逾時
  等待 1 秒
嘗試 2: POST /labels → 500
  等待 2 秒
嘗試 3: POST /labels → 200（冪等重放 — 標籤在嘗試 1 時已建立）

重試失敗的標籤

失敗的標籤對其 idempotencyKey 而言是最終結果，且會保留其 customerOrderNumber。請先修正原因 — 地址、產品代碼或帳戶設定。大多數物流業者拒絕並非暫時性問題。接著送出一個新的請求，使用新的 idempotencyKey 與新的 customerOrderNumber（或省略此欄位以自動產生）。重複使用該編號會回傳 409 DUPLICATE_CUSTOMER_ORDER_NUMBER。建議的模式是附加嘗試次數後綴，例如 N-2026-05-27-TEST-03-2，並將完整訂單編號控制在 40 個字元以內。請將您原始的訂單參考保留在 order.orderNumbers.referenceNumbers 中。允許使用的字元請參閱客戶訂單編號。失敗標籤所回傳的錯誤內容，請參閱下游物流業者錯誤 502 與 422。

各端點的冪等性

端點	冪等	機制
`POST /labels`	是	`idempotencyKey` 欄位 — 每個請求中必填
`GET /labels/{id}`	是	唯讀 — 天然冪等
`GET /tracking/{id}`	是	唯讀 — 天然冪等

失敗場景

收到回應前的網路逾時

標籤可能已建立也可能未建立。請使用相同的 idempotencyKey 和未修改的本文重試。若已儲存嘗試結果，API 會以 HTTP 200 回傳該結果，包含任何已儲存的失敗結果。否則會再次嘗試建立；成功則回傳 HTTP 201。

HTTP 500 內部伺服器錯誤

暫時性伺服器錯誤。使用相同的 idempotencyKey 並以退避策略重試。

HTTP 502 錯誤閘道（物流業者錯誤）

物流業者拒絕了請求。標籤已在此 idempotencyKey 下以 status: failed 儲存。使用相同金鑰重試會以 HTTP 200 回傳相同的失敗結果，且不會再次聯絡物流業者。若要重新嘗試，請參閱「重試失敗的標籤」。

HTTP 400 驗證錯誤

請求無效。未修正請求前請勿重試。由於未建立標籤，修正請求本文後可以重複使用相同的 idempotencyKey。

HTTP 409 衝突

請先查看 code。IDEMPOTENCY_CONFLICT 表示應使用原本文，或為修改後的請求使用新金鑰。DUPLICATE_CUSTOMER_ORDER_NUMBER 表示應取得現有標籤，或選擇其他訂單編號。請勿針對未變更的衝突請求持續重試。

快速開始

指南

使用場景指南

平台

冪等性與重試

冪等性與重試

冪等性的運作方式

選擇冪等性金鑰

重試策略

重試失敗的標籤

各端點的冪等性

失敗場景

​冪等性與重試

​冪等性的運作方式

​選擇冪等性金鑰

​重試策略

​重試失敗的標籤

​各端點的冪等性

​失敗場景

冪等性與重試

冪等性的運作方式

選擇冪等性金鑰

重試策略

重試失敗的標籤

各端點的冪等性

失敗場景