IOSOR 知識庫

在 API 重試邏輯中處理 HTTP 402 與 429 狀態碼

透過針對 HTTP 402 與 429 狀態碼採用不同的帳戶餘額邏輯，為白標預付費 CPaaS 掌握具韌性的 API 重試模式。

理解預付費 CPaaS HTTP 狀態架構

建構自動化通訊整合時，軟體依賴可預測的 HTTP 回應來維持正常運行時間。與額度具彈性的標準後付費軟體不同，白標預付費 CPaaS 運行於嚴格的帳戶餘額與即時資金模型。每個 API 請求——無論是發送 OTP、串流 SMS 還是註冊 webhook——都會針對您的有效錢包餘額觸發即時授權檢查。由於資金必須到位，因此理解狀態碼至關重要。預付費錢包 (Prepaid wallet) 的餘額直接影響 API 的可用性，任何超出預算的請求都可能被拒絕。這與後付費模式截然不同，後付費模式通常允許在一定額度內超支，並在之後進行帳單結算。

HTTP 402 Payment Required 的剖析與預付費錢包保持

HTTP 402 狀態碼表示操作失敗，因為您的帳戶餘額已耗盡或無法涵蓋預估的 MRC 與使用成本。當您執行即時調配時，系統會強制進行預付費錢包保持 (Prepaid wallet holds)，確保號碼指派與訊息發送有足夠資金。如果您的餘額跌破 USD 20 的預付費底線，閘道會立即拒絕發送酬載並回傳 402 錯誤。將此視為暫時性網路問題將導致重複失敗。當發生此類財務拒絕時，必須暫停外寄流量並等待加值確認。為了確保持續運作，系統會持續監控預付費錢包保持狀態，並在餘額獲得補充時自動解凍執行緒。這意味著，在進行任何需要預付款項的操作前，必須確保錢包中有足夠的餘額。例如，發送大量 SMS 或購買新的電話號碼都需要預先支付費用。

HTTP 429 Too Many Requests 的剖析與吞吐量管理

相比之下，HTTP 429 回應發出速率限制事件的訊號，這是因超過吞吐量閾值 (例如每秒發送過多 Verify OK 請求) 所觸發的。雖然 402 錯誤代表財務阻礙，但 429 錯誤純粹是營運性質且短暫的。當您的系統遇到 429 狀態時，回應標頭通常包含 Retry-After 指令，指示您的工作執行緒在發送下一個酬載之前應暫停幾秒鐘。透過平滑的佇列與速率調節機制，可以有效防止下游服務過載並維持連接穩定。在此期間，應動態調整併發請求數量，以適應閘道的即時容量限制並維持最佳吞吐量。這通常透過在客戶端實現指數退讓 (exponential backoff) 和抖動 (jitter) 來處理，以避免請求風暴。

設計智慧重試策略、靜音時段與拒收同步

編寫具韌性的客戶端程式碼需要根據狀態碼將錯誤管理分開。對於 HTTP 429，請實作具有隨機退讓與嚴格上限限制的重試迴圈以順利恢復。對於 HTTP 402，請觸發可暫停外寄流量的熔斷器、觸發自動化帳戶加值或向管理員發出警報，並等待資金已結清的 webhook 確認。此外，在處理發送時必須遵守各國法規定義的靜音時段 (Quiet hours)，避免在深夜打擾用戶，同時確保將使用者的退訂與拒收狀態 (Opt-out sync) 即時同步至本地資料庫，以避免向已拒收的使用者重複發送訊息，確保合規性與客戶滿意度。靜音時段的設定應基於目標市場的當地時間，並在 API 請求中明確指定或通過配置進行管理。

整合帳戶檢查、DLR 與 Webhook 真相來源

為了優化系統效能，請將預先檢查帳戶餘額與智慧佇列管理相結合。在推送大量 SMS 行銷活動或處理大容量 E.164 目標列表之前，請查詢您的帳戶餘額端點以確保您清除最低營運閾值。在訊息發送後，絕對不能依賴客戶端發送狀態作為最終結論，而應將伺服器端收到的遞送報告 (DLR) 與 Webhook 事件作為唯一的真實狀態來源 (Webhook truth)。透過核對這些非同步回呼，您可以精確追蹤每一則訊息的生命週期，並據此調整重試邏輯與會計帳目。DLR 的接收和處理是確保訊息送達的關鍵，它提供了訊息被電信商接收、傳送或最終失敗的詳細資訊。

使用 IOSOR 開始建立可靠的 CPaaS 基礎設施

把用戶端分叉：HTTP 402 表示預付 hold 失敗或錢包無法結算——停掉意圖，出示儲值，不要重試。HTTP 429 表示速率視窗已滿——遵守 Retry-After，用同一把 Idempotency-Key 重發。一個把兩個碼都重試的處理會鑄出第二場扣款風暴。在處理 402 時，應觸發一個熔斷器模式，暫停所有出站流量，直到預付費錢包中的資金得到補充。對於 429，則應實施一個帶有抖動的指數退讓重試機制，並確保每次重試都帶有相同的 Idempotency-Key，以避免重複計費或處理。這兩種狀態碼的區別處理是維持帳戶穩定性和服務連續性的關鍵。

IOSOR 要點

402 是資金停止；429 是節奏暫停。它們不是同一種重試。在客戶端實現邏輯時，必須區分這兩種情況。402 意味著需要補充資金，而 429 則意味著需要暫時降低請求速率。正確處理這兩種狀態碼可以防止不必要的 API 調用失敗，並確保服務的穩定運行。例如，當收到 402 時，應通知使用者補充資金，並暫停所有相關的 API 操作，直到資金到位。而收到 429 時，則應根據 `Retry-After` 標頭的值暫停請求，並在之後以指數退讓的方式重試。

要做：402 上停到新 hold 能結算；429 帶著原鍵退避，讓預付只看見一個意圖。對於 402 錯誤，應暫停所有出站請求，直到預付費錢包中的餘額得到補充，並且能夠成功建立新的預付費保持 (hold)。對於 429 錯誤，則應在遵守 `Retry-After` 指令的同時，使用相同的 Idempotency-Key 進行重試。這確保了即使在速率限制期間，請求也能被正確處理，並且不會產生重複的費用或操作。這種精確的錯誤處理對於維持服務的可靠性和用戶體驗至關重要。

不要：把 402 當成軟 429，或在帳本還在決定時把任一碼砸到 200。將 402 錯誤誤判為 429 錯誤，並嘗試重試，可能會導致進一步的資金耗盡和帳戶問題。同樣，在帳戶餘額或交易狀態仍在處理中時，將任何錯誤碼返回 200 OK，會掩蓋潛在的問題，並可能導致不準確的計費或服務中斷。始終確保 API 回應準確反映實際狀態，並根據相應的 HTTP 狀態碼採取適當的行動。

這篇指南有幫助嗎？