AI API 報錯與重試:別讓一個問題變成兩個
區分需要修改的請求和可以重試的故障,避免非同步任務被重複建立。

重複之前先看清失敗原因
請求格式錯誤、金鑰無效或引數不受支援,通常需要修改配置,而不是原樣再發一次。對於限流或暫時性服務錯誤,可按介面文件判斷是否重試。記錄狀態和請求標識,但不要把憑據或敏感提示詞寫進日誌。
認證或許可權錯誤需要檢查金鑰與訪問範圍;請求格式、模型名稱或引數錯誤需要修改輸入;限流與部分臨時服務故障可能適合稍後重試。具體狀態碼和錯誤內容以介面文件為準。把這些情況全部歸為“網路異常”會讓使用者和開發者都失去有用線索,也容易觸發沒有意義的重複請求。
給暫時性故障恢復的時間
對於適合重試的故障,設定有上限的重試次數、退避和隨機抖動;服務端提供等待時間時也應遵守。設定整體截止時間,別讓使用者無限等待。不要對所有錯誤一律重試,也要避免大量客戶端在同一瞬間再次請求。
對文件允許重試的情況,可以限制次數和總耗時,逐步增加等待時間,並加入隨機抖動,減少多個客戶端同時重試造成的壓力。服務端提供明確等待時間時應優先遵守。一個合理的策略還要允許使用者取消,並在達到上限後結束,而不是在後臺無期限地消耗資源。
遇到暫時性故障時,等待後再依受控策略重試。有副作用的任務要格外小心
應用收到超時時,遠端可能已經接受請求。再次建立圖片或影片任務可能重複執行併產生費用。介面返回任務標識後應儲存,重新提交前先查詢狀態;只有介面明確支援時,才依賴其冪等機制。
提交生成任務後發生超時,可能只是響應沒有及時到達,遠端任務卻已經建立。拿到任務 ID 時先儲存並查詢;沒有拿到 ID 時,不要假設任務一定不存在。檢查介面是否提供查詢、回撥或明確的冪等機制,並按文件處理未知狀態。只有在瞭解可能的額外費用後,才發起新的建立請求。
給等待的人一個明確的下一步
告訴使用者應該重試、修改輸入還是稍後再試。適當保留已顯示的流式內容,並說明它尚未完成。分別測試無效請求、限流、網路中斷和任務延遲,它們不應全部顯示成同一個含糊的錯誤。
記錄時間、請求標識、介面、狀態碼、耗時和必要的錯誤類別,通常足以開始排查。不要寫入完整金鑰、授權頭或不必要的使用者提示詞;分享日誌前還應檢查個人資訊。把客戶端可見提示與內部診斷資訊區分開:使用者需要知道下一步,維護者則需要可追蹤的上下文。
在測試環境分別模擬無效引數、身份驗證失敗、限流、連線中斷和處理緩慢的非同步任務。觀察是否只對合適的錯誤重試、等待時間是否有上限、介面是否保留部分結果。還應檢查使用者連續點選重試時是否會建立重複任務。演練不需要真實客戶資料,也不應向生產環境傳送會產生費用的任務。
先判斷失敗屬於哪一類
當請求失敗時,先保留狀態碼、請求標識、發生時間和脫敏後的錯誤型別。認證失敗通常需要檢查金鑰、許可權或賬戶配置;請求格式和引數錯誤需要修改輸入;限流與臨時服務故障則可能適合稍後重試。具體行為以介面文件和實際響應為準,不要把每一種錯誤都塞進同一個自動重試迴圈。
網路超時尤其需要區分發生階段。如果連線尚未建立,服務可能沒有收到請求;如果請求已經傳送而響應丟失,服務可能正在處理,甚至已經完成。客戶端看到的超時不能單獨證明遠端沒有執行。對建立任務、傳送訊息或修改資料的操作,這個區別會影響重複執行和費用。
錯誤提示要對使用者有幫助,同時避免暴露金鑰、內部地址或原始堆疊。可以說明操作沒有完成、是否保留了已輸入內容、使用者是否可以稍後再試。對需要支援團隊排查的問題,提供請求標識比讓使用者截圖完整敏感內容更合適。
給重試設定邊界
對於明確可重試的暫時性錯誤,可以設定最大次數和總等待時間,並隨著重試次數增加等待間隔。加入隨機抖動有助於避免大量客戶端在同一時刻再次請求。若響應或文件提供等待建議,應優先按照其規則處理;不要把一個固定的演示數字當成所有服務的通用限制。
在多層系統中尤其要注意重試疊加:瀏覽器、業務服務和客戶端庫如果各自重試,最終請求次數可能遠大於預期。儘量明確由哪一層負責,並記錄每次嘗試的結果。超過限制後停止並返回可理解的狀態,避免長時間佔用連線或讓使用者以為操作仍然順利進行。
只讀查詢通常比建立操作更容易安全重試,但仍需遵守介面限制。有副作用的請求應使用服務實際支援的冪等機制,或者先查詢已知任務狀態。不要自行聲稱任意介面都支援冪等鍵;如果沒有可靠的去重方式,就應明確提示使用者並謹慎處理不確定結果。
用兩個例子檢驗策略
第一種情況:使用者傳送文字請求,服務明確返回限流提示。應用可以保留輸入,按照允許的等待時間和重試上限嘗試恢復,並在等待期間讓使用者取消。如果多次嘗試仍失敗,說明現在無法完成,而不是無限顯示載入動畫。
第二種情況:使用者提交影片生成後,網路在返回任務標識前中斷。此時應用不能確定任務是否已經建立。應使用介面支援的查詢或恢復方式核實;如果無法核實,清楚告知使用者狀態不確定,避免後臺悄悄重複建立多個任務。重新生成是否收費應以實際規則為準。
把這兩類情況加入自動化測試,再加入無效金鑰、錯誤引數、連線中斷和使用者取消。核對每一層的嘗試次數、最終提示和日誌是否符合預期。好的重試策略不是儘可能多地重發,而是在恢復機會、使用者體驗和重複操作風險之間保持清晰的邊界。
最後,不要忘記檢查告警本身:如果每次暫時性失敗都觸發高優先順序通知,團隊很快會忽略真正的問題。按持續時間、影響範圍和是否自動恢復區分告警等級,並定期回看哪些重試實際上解決了問題。
兩種失敗,兩種處理
如果請求被限流,且服務返回了重試等待時間,就在重試次數與總時限內按提示等待。如果影片建立請求在提交後超時,任務可能已經存在:先查詢已儲存的任務 ID 並查詢狀態。如果沒有拿到 ID,應明確說明狀態不確定,按介面文件處理,而不是假定再次提交不會產生費用。
使用者聯絡支援時,優先請其提供發生時間、模型名稱和請求標識,以及經過脫敏的錯誤說明。不要要求使用者在公開渠道傳送金鑰或完整私人內容。維護者應根據記錄核對請求是否已建立任務,再給出明確的排查步驟或安全的重試建議。