Tracking API 錯誤處理：如何管理無效追蹤號碼、速率限制及重試

處理追蹤 API 錯誤時，應區分無效輸入、暫時性故障、速率限制及貨件狀態結果。對無效的追蹤編號，應拒絕或修正，而不是在未作變更的情況下重試；受到節流時，應協調請求量；對暫時性故障，則使用有上限的指數退避及抖動進行重試。在重複註冊或其他寫入請求前，先確認第一次嘗試是否已成功。

對於將追蹤資料連接至訂單管理系統、倉庫平台或面向客戶的追蹤頁面的開發人員而言，目標不只是減少失敗請求，而是可靠地顯示貨件狀態，同時避免重複註冊、重試風暴、誤導性的配送訊息或不必要的支援工單。

選擇回應前先分類故障

追蹤整合需要評估幾種不同結果：網絡請求是否完成、API 是否接受操作、每個所請求的追蹤項目是否成功，以及貨件事件是否可用。將這四項全部視為單一的成功或失敗標記，會造成可避免的錯誤。

HTTP 成功回應不一定代表批次中的每個項目都成功。相反，已成功處理但沒有追蹤事件的查詢，也不一定代表 API 發生故障。請檢查回應主體，並按供應商文件所記載的含義處理每個結果。

情況	建議行動	是否原樣重試？
格式錯誤的編號或無效請求欄位	驗證並修正輸入	否
缺少或無效的憑證	檢查憑證、權限及環境	修正前不可
速率限制回應	延遲受影響的工作，並減低共享請求壓力	在所需等待時間後，若安全則可以
暫時性服務故障	套用有上限的退避，並檢查操作是否安全	通常可以，但須在重試預算內
提交註冊後逾時	核對註冊是否已存在	不可盲目重試
已接受查詢但沒有貨件事件	遵循文件記載的追蹤生命週期	使用定時刷新，而非快速重試

HTTP 狀態碼只是起點，並不是完整的供應商專用決策樹。RFC 9110 定義 HTTP 語義，而 RFC 6585 定義 429 Too Many Requests。你的整合亦應解讀文件記載的應用程式錯誤碼及項目級結果。

無效追蹤編號：區分錯誤輸入與缺少事件

「無效追蹤編號」可能描述不同問題：格式錯誤的識別碼、不受支援的承運商與編號組合、缺少必要的承運商欄位，或其他供應商專用的驗證失敗。不要僅因沒有返回追蹤事件，就假定編號無效。

在不損壞識別碼的情況下進行驗證

• 將追蹤編號儲存為字串。以數值儲存可能會刪除前導零或改變較長的識別碼。
• 保留原始輸入。另行保存標準化值，讓所有轉換均可追溯。
• 保守地進行標準化。在適當情況下移除前後空白，但只有在文件規則允許時，才移除內部字元或變更字母大小寫。
• 在本地檢查必要欄位。在發送前捕捉空白編號、缺少承運商識別碼及無效的請求結構。
• 避免使用通用追蹤編號正規表示式。為一間承運商設計的規則，可能會拒絕另一間承運商的有效識別碼。
• 確認欄位所包含的內容。除非端點明確支援，否則訂單編號、倉庫參考編號及承運商追蹤編號不能互換。

如果 API 明確拒絕輸入，應將其導向修正流程，而不是進入自動重試循環。請提供有用的原因，例如「需要承運商識別碼」，而不要將所有驗證問題簡化為「追蹤失敗」。

將「沒有事件」視為獨立狀態

貨件可能已經有追蹤識別碼，但尚未提供有用的運輸事件。正確回應取決於 API 文件記載的狀態模型及貨件情境。檢查識別碼是否來自出貨系統、承運商選擇是否正確，以及回應表示的是資料等待中，而不是輸入被拒絕。

使用不同的內部狀態，例如 input_rejected、awaiting_events 及 temporarily_unavailable。這些是建議的應用程式狀態，並非標準化的 API 值。它們有助於防止暫時性的資料空缺變成不準確的客戶訊息。

在整個整合範圍內管理速率限制，而非按工作程式管理

RFC 6585 將 HTTP 429 定義為速率限制回應，並允許其包含 Retry-After 標頭。該標準沒有規定通用的追蹤 API 配額或計算方式。限制可能按帳戶、憑證、端點或其他範圍記載；請使用供應商的實際規則。

RFC 9110 指定 Retry-After 的兩種形式：非負秒數或 HTTP 日期。請解析兩者。如果值是日期，請仔細計算剩餘等待時間，並考慮時鐘差異。如果值缺失或無法使用，請套用已設定的後備退避政策。

當其他工作程式仍使用相同配額時，單一工作程式獨立睡眠並不足夠。應在相關憑證或帳戶的共享邊界實施速率控制。中央排程器、共享令牌桶或同等的分散式控制機制，可以協調相關流量。

1. 識別受影響的範圍。確定限制適用於哪個端點、憑證或帳戶。
2. 遵守伺服器的等待指示。不可安排早於有效 Retry-After 值所允許時間的重試。
3. 延遲受影響的排隊工作。當限制確實彼此獨立時，避免阻塞不相關流量。
4. 降低並行數或請求頻率。只等待一次而不改變請求模式，可能會再次造成相同問題。
5. 分隔流量後恢復。等待結束時，不要同時釋放整個積壓佇列。

在支援的情況下，批次處理可以減少請求數量，但必須遵守文件記載的批次大小及計算規則。不要假設一個批次只消耗一個配額單位。同樣地，在可用時使用 webhook 以減少不必要的輪詢，同時保留整合所需的核對流程。

使用帶退避及抖動的有上限重試

當故障可能在不改變請求的情況下自行消失，且重複操作安全時，重試便是合適做法。暫時性的連線故障及部分伺服器錯誤可能屬於此類。格式錯誤的負載、無效憑證或永久性權限問題，通常需要先修正。

實際可行的後備方案是帶完整抖動的封頂指數退避：

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

在此，retry_index 在第一次重試時從零開始，而缺少的 Retry-After 不會增加最低等待時間。這些是實作選擇，而不是強制性的 HTTP 演算法。請根據工作負載及供應商指引，選擇基礎延遲、上限、嘗試次數限制及總截止時間。

抖動會將請求分散到不同時間，而不是讓每個工作程式按相同時間表重複請求。延遲上限限制指數部分；不應覆蓋伺服器要求的較長有效等待時間。如果該等待時間超過工作截止時間，應按政策延後或終止工作，而不是提早重試。

為每個重試鏈設定終點

• 嘗試次數限制：限制額外請求的數量。
• 經過時間限制：停止重試已超出有效處理時限的工作。
• 明確的負責層級：選定由哪一層控制重試，避免 HTTP 用戶端重試與佇列重試意外倍增。
• 持久化排程：儲存延遲工作，而不是依賴短命程序內的長時間睡眠。
• 復原路徑：將耗盡重試次數的工作連同原因及下一步行動，送至可供檢視的失敗工作佇列。

在持續性服務中斷期間，可考慮使用斷路器，暫時停止例行呼叫，並允許受控的復原探測。這是應用程式韌性模式，不代表任何特定追蹤供應商要求使用它。

重新發送前先解決不明確的寫入結果

逾時表示你的應用程式沒有收到完整回應，但不代表伺服器已拒絕或從未處理該請求。在註冊追蹤編號或變更追蹤設定時，這項區分非常重要。

RFC 9110 解釋了冪等方法，並提醒在沒有依據確定重複操作安全，或原始操作未被套用時，不應自動重試非冪等請求。應評估文件記載的操作語義，而不是假設每個追蹤端點都像唯讀查詢一樣運作。

• 在可用時使用供應商文件記載的冪等機制，並遵循其範圍及保留規則。
• 對同一邏輯操作的重試使用相同冪等鍵；不要假設任意自訂標頭都會被採用。
• 如受支援，請在重複不明確的寫入前，檢查現有註冊。
• 使用符合供應商文件記載的貨件識別方式的本地唯一性約束。
• 儲存操作結果，避免佇列重新派送時自動觸發另一次寫入。

對於批次操作，請保存每個項目的結果。只重試被分類為暫時性失敗的項目，並核對結果仍然未知的項目。重播整個批次可能會重複已成功的工作，並不必要地消耗請求配額。

將政策套用至你的追蹤供應商

對於 17TRACK 整合，請以Tracking API page及official API documentation作為了解供應商專用合約的起點。錯誤分類器應保持可配置，不要將通用 HTTP 指南中的假設硬編碼。

在實作前，確認相關端點的請求結構、回應封裝、項目級錯誤含義、速率限制範圍、批次限制及重複提交規則。如使用事件傳送，也要核實確認、驗證及重新派送要求。本指南不會指定 17TRACK 的數值速率限制、重試排程或冪等功能。

將每項已確認的規則記錄在由供應商回應至應用程式行動的映射中：修正輸入、修復設定、等待、核對或升級處理。未識別的錯誤應保留診斷內容，並遵循有上限的後備路徑，而不是預設進行無限重試。

監察復原質素並測試故障路徑

記錄操作、端點、HTTP 狀態、應用程式錯誤碼、嘗試次數、延遲、下一項排程行動，以及供應商提供的請求識別碼。避免記錄 API 金鑰、不必要的地址資料或不受限制的回應主體。不需要完整值時，應遮蔽或雜湊追蹤識別碼。

分別追蹤無效輸入率、節流、佇列年齡、耗盡的重試及最近一次成功同步。即使 HTTP 錯誤率較低，整合仍可能提供過時的貨件資料。面向客戶的頁面應保留最近已知的貨件狀態，並區分刷新失敗與承運商回報的配送異常。

發佈前，測試格式錯誤的輸入、沒有事件的有效識別碼、Retry-After 的兩種形式、缺少標頭、部分批次失敗、寫入後逾時及佇列重新派送。同時模擬持續時間足以耗盡重試預算的服務中斷。只有在工作可預測地停止或延後、成功項目不會被不必要地重播，以及失敗項目仍可復原時，測試才算通過。

常見問題

無效追蹤編號是否應自動重試？

當 API 明確拒絕輸入為無效時，不應自動重試。請先修正編號、承運商選擇或必要欄位。如果回應其實表示貨件事件尚未可用，應使用文件記載的刷新流程，而不是將其視為驗證失敗。

HTTP 200 是否代表批次請求完全成功？

不一定。請檢查供應商的回應結構，以了解操作級及項目級結果。保存成功項目並隔離失敗項目，避免重試一個項目時不必要地重複其餘項目。

追蹤整合應允許多少次重試？

沒有通用次數。應根據供應商指引、操作安全性及結果在多長時間內仍然有用，設定嘗試次數限制及經過時間預算。排程的背景同步與互動式客戶請求，可容許不同的復原時限。

逾時後是否應立即將貨件標記為失敗？

不應。請求逾時是整合結果，而不是貨件事件。保留最近已知的追蹤狀態，安排安全的復原，並避免將連線問題轉化為配送失敗通知。

重試耗盡後應怎樣處理？

將工作連同診斷內容移至持久化的失敗工作或檢視佇列。確認復原需要修正輸入、恢復憑證、供應商協助，還是稍後進行受控重播。不要靜默丟棄，也不要重新開始相同的無限重試循環。

來源

• RFC 9110: HTTP Semantics — HTTP 狀態語義、冪等方法、自動重試考慮因素及 Retry-After 欄位。
• RFC 6585: Additional HTTP Status Codes — 429 Too Many Requests 的定義及其可選的 Retry-After 標頭。
• 17TRACK Tracking API — 追蹤 API 產品的官方入口。
• 17TRACK API documentation — 查閱供應商專用整合要求的參考資料。