作者注：本文按錯誤碼講解 AI API 報 429、401、500 時的原因和處理方式，說明哪些錯誤該重試、哪些該修配置，以及指數退避、多模型降級和熔斷各自適用的範圍。
線上調用大模型時，凌晨告警羣裏出現一串 429、401、500，是很多開發者都經歷過的場景。常見的應對是給所有失敗請求加一層重試，但這樣做往往讓情況更糟。本文按錯誤碼分類講解 AI API 報 429、401、500 時的判斷方法與容錯設計，幫你把“盲目重試”換成“分類處理”。
這不是一篇 HTTP 狀態碼科普，而是面向線上運維的實踐指南。內容包括每類錯誤的典型原因、能不能重試、應用層怎麼寫處理邏輯，以及網關層和應用層容錯怎麼分工。
核心價值：讀完本文，你能在幾分鐘內判斷一個報錯該重試、該降級還是該立即修配置，並清楚指數退避、多模型降級和熔斷各自適合什麼場景。
AI API 報 429、401、500 的核心要點
處理 AI API 報錯，第一步是分類，重試放在後面。不同錯誤碼代表的問題性質不同，有的等一會兒就能自愈，有的不管重試多少次都會失敗。下表先給出三類錯誤的整體判斷。
| 錯誤類別 | 典型狀態碼 | 問題本質 | 能否重試 | 核心處理方式 |
|---|---|---|---|---|
| 限流類 | 429 | 請求太快或額度耗盡 | 視原因而定 | 讀取 Retry-After，指數退避，區分限流與額度不足 |
| 認證類 | 401、403 | 密鑰無效、權限不足 | 不能 | 立即停止重試，告警並修正配置 |
| 服務端類 | 500、502、503、504 | 上游故障或過載 | 可以，有上限 | 有限次退避重試，持續失敗時降級或熔斷 |
| 請求類 | 400、404、413、422 | 參數、模型名、長度有誤 | 不能 | 記錄請求體，修正參數後再發 |
可以看出，能不能重試取決於錯誤是暫時的還是確定的。暫時性錯誤（限流、上游抖動）重試有意義。確定性錯誤（密鑰錯、參數錯）重試只會浪費額度、拖慢響應，還可能觸發更嚴格的限流。
AI API 錯誤碼判斷決策表
實際排查時，光看狀態碼還不夠，還要結合響應體裏的錯誤類型字段和響應頭。下表是一份可以直接用於設計應用層邏輯的決策表。
| 觀察到的信號 | 可能原因 | 推薦動作 | 是否計入熔斷統計 |
|---|---|---|---|
429 且帶 Retry-After 頭 |
速率限制 | 按頭部給出的時間等待後重試 | 否 |
| 429 且錯誤體提示額度/餘額不足 | 賬戶額度耗盡 | 不重試，告警充值或切換賬戶 | 否 |
| 401 | 密鑰錯誤、過期或格式不對 | 不重試，檢查密鑰與環境變量 | 否 |
| 403 | 密鑰無權訪問該模型或區域 | 不重試，檢查權限與模型開通情況 | 否 |
| 500 / 502 | 上游內部錯誤、網關轉發失敗 | 退避重試 2-3 次 | 是 |
| 503 | 服務過載或維護 | 退避重試，失敗後降級 | 是 |
| 504 或客戶端超時 | 生成太長、上游響應慢 | 視冪等性決定是否重試，考慮調大超時 | 是 |
表裏最容易被忽略的是 429 的兩種含義。部分服務商在額度耗盡時也返回 429，但錯誤體裏的類型字段和普通限流不同。如果應用層只看狀態碼，就會對一個“餘額不足”的請求無限退避重試，日誌裏全是 429，卻始終不會恢復。
429 限流錯誤重點詳解
429 的核心原因是單位時間內請求數或 token 數超過了限制。大模型 API 的限流通常有多個維度：每分鐘請求數、每分鐘 token 數，有的還有併發數限制。所以即使請求數不多，一次塞進超長上下文也可能觸發 429。
應用層處理 429 有三條原則。第一，優先遵守 Retry-After 或類似的重置時間頭，不要自己猜等待時間。第二，在沒有頭部提示時使用帶隨機抖動的指數退避，避免大量客戶端同時醒來再次打滿限額。第三，從源頭控流，用令牌桶或隊列限制併發，比事後重試更有效。
401 認證錯誤重點詳解
401 是最不該重試的錯誤。它幾乎總是由配置問題引起，常見情況有：密鑰複製時多了空格或換行，環境變量在容器裏沒有正確注入，測試環境的密鑰被帶到了生產，密鑰已被輪換或吊銷，或者使用了錯誤的鑑權頭格式。
在 OpenAI 兼容接口下，還有一個高頻原因是 base_url 和密鑰不匹配，比如用 A 平臺的密鑰請求 B 平臺的地址。因此 401 出現時，應用層應當立即停止重試、觸發高優先級告警，並在日誌中記錄密鑰前幾位與請求地址，方便快速定位，但不要記錄完整密鑰。
500 服務端錯誤重點詳解
500 系列錯誤說明問題在服務端或鏈路上，可能是上游模型服務內部異常、負載過高，也可能是中間網關轉發失敗。這類錯誤通常是暫時性的，適合有限次數的重試。但如果持續出現，就說明上游進入了不健康狀態，這時繼續重試只會讓請求排隊、線程被佔滿，應該轉向降級或熔斷。
還要注意 504 和客戶端超時。大模型生成長文本本身就慢，如果超時時間設得太短，會把正常的慢請求誤判爲失敗，然後重試，這會產生重複計費，在流式輸出中斷時還會讓前端收到截斷的內容。
AI API 重試、降級與熔斷快速上手
分好類之後，就要把處理邏輯落到代碼裏。按照補充要求，本節不貼代碼塊，而是用參數清單和步驟說明講清每種機制的實現要點，你可以照着在任意語言裏實現。
指數退避重試的實現要點
指數退避的思路是：每次重試的等待時間按倍數增長，再疊加隨機抖動。實現時可以按下面的步驟組織邏輯：
- 定義可重試的錯誤集合，例如
429（非額度不足）、500、502、503、504以及網絡超時。 - 每次失敗後先檢查響應頭裏的
Retry-After，有就按它等待，沒有則按退避公式計算等待時間。 - 等待時間公式通常寫成“基礎間隔 × 2 的重試次數次方”，再加上一個隨機抖動值，並設置單次等待上限。
- 設置最大重試次數和總耗時預算，任何一個超限都立即放棄，把錯誤交給降級邏輯。
- 每次重試都記錄日誌，包括錯誤碼、重試次數、等待時長和模型名，方便事後分析。
如果你使用官方 SDK，很多 SDK 本身已有 max_retries、timeout 之類的參數。這時要注意不要在外層再包一層同樣的重試，否則重試次數會相乘，故障時請求量成倍放大。
下表給出一組常見的起步參數，屬於經驗值，具體數值應根據你的業務延遲要求和服務商限額調整。
| 參數 | 含義 | 常見起步取值 | 調整依據 |
|---|---|---|---|
max_retries |
最大重試次數 | 2-5 次 | 實時對話取小值，離線批處理可取大值 |
| 基礎間隔 | 首次重試等待 | 約 1 秒 | 限流嚴格的服務可適當放大 |
| 單次等待上限 | 退避時間封頂 | 數十秒級 | 避免單次等待過長拖垮請求 |
| 隨機抖動 | 打散重試時間 | 等待時長的一部分隨機值 | 併發客戶端越多越需要 |
| 總耗時預算 | 一次調用最長耗時 | 按業務 SLA 設定 | 超時後直接降級 |
🚀 快速開始：如果想在測試階段模擬不同錯誤碼下的重試表現，可以通過 API易 apiyi.com 用統一的 OpenAI 兼容接口接入多個模型，在同一套重試邏輯下觀察不同模型的響應和報錯情況，減少爲每家服務商單獨適配的工作量。
多模型降級的設計方法
重試解決的是“同一個模型暫時不可用”，降級解決的是“這個模型短時間內恢復不了”。多模型降級就是預先配置一條備用鏈路：主模型連續失敗後，按順序切換到備用模型，保證業務能繼續響應，代價是可能犧牲一部分質量或增加一部分成本。
設計降級鏈時要考慮能力是否等價。如果主模型依賴函數調用、結構化輸出或長上下文，備用模型也必須支持這些特性，否則降級後會出現新的 400 錯誤或輸出格式解析失敗。下表給出一種按場景設計降級鏈的參考思路。
| 業務場景 | 主模型定位 | 一級備用 | 二級兜底 | 可用平臺 |
|---|---|---|---|---|
| 在線客服對話 | 高質量通用模型 | 同級別的其他廠商模型 | 輕量快速模型 + 簡化回覆 | API易 apiyi.com、各家官方 API |
| 代碼生成與審查 | 編程能力強的旗艦模型 | 另一家旗艦模型 | 返回“稍後重試”提示 | API易 apiyi.com、各家官方 API |
| 批量內容處理 | 性價比模型 | 同價位其他模型 | 寫入隊列延後處理 | API易 apiyi.com、各家官方 API |
| 結構化信息抽取 | 支持 JSON 輸出的模型 | 同樣支持結構化輸出的模型 | 規則引擎兜底 | API易 apiyi.com、各家官方 API |
降級時有幾個細節需要處理好：
- 提示詞適配：不同模型對系統提示詞的敏感度不同，備用模型最好有經過驗證的獨立提示詞版本。
- 上下文長度：切換前檢查消息長度是否超過備用模型的上下文窗口，必要時先截斷歷史。
- 結果標記：在日誌和監控裏標記“本次響應來自降級模型”，便於評估降級對質量的影響。
- 不要降級認證錯誤：401 說明配置有問題，切換模型只會掩蓋問題，應該直接告警。
熔斷器的工作原理與使用邊界
熔斷器用來防止一個持續故障的依賴拖垮整個系統。它通常有三種狀態：關閉時請求正常放行，同時統計失敗率；失敗率或連續失敗次數超過閾值後進入打開狀態，此時直接拒絕請求或走降級，不再訪問故障上游；經過一段冷卻時間後進入半開狀態，放少量試探請求，成功則恢復關閉，失敗則重新打開。
熔斷的關鍵是只統計能代表上游健康度的錯誤。5xx 和超時應該計入失敗率，而 401、400 這類客戶端錯誤不應計入，否則一個配置錯誤就會讓熔斷器打開，所有正常請求都被拒絕。按額度不足返回的 429 也不應計入，它反映的是賬戶狀態，不是服務健康度。
熔斷也不是越多越好。對於調用量很低的內部工具，失敗率統計樣本太少，熔斷器容易誤判，這時用簡單的重試加降級就夠了。熔斷更適合高併發的線上服務，它能在上游大面積故障時快速止損，避免線程池和連接池被慢請求佔滿。
網關層與應用層容錯的分工
越來越多團隊通過 API 網關或聚合平臺調用大模型。這時常見的疑問是：網關已經有自動降級，應用層還要不要做重試和熔斷？答案是要做，但分工不同。網關擅長處理“上游渠道”層面的問題，應用層更瞭解“業務語義”層面的問題，兩邊各管一段。
| 容錯職責 | 網關層更適合 | 應用層更適合 |
|---|---|---|
| 渠道故障切換 | 同一模型多渠道切換、負載均衡 | 無需重複實現 |
| 跨模型降級 | 可提供模型路由能力 | 決定業務是否接受質量降級、是否需要換提示詞 |
| 重試 | 渠道級的快速重試 | 業務級重試預算、與用戶超時體驗協調 |
| 熔斷 | 針對上游渠道的健康檢查 | 針對整個網關不可達的熔斷與兜底 |
| 認證與額度錯誤 | 返回明確的錯誤類型 | 告警、阻斷重試、通知人工處理 |
| 監控 | 渠道層面的成功率與延遲 | 業務層面的成功率、降級比例、用戶影響 |
以 API易 爲例，其業務介紹中提到了自動降級、負載均衡和實時監控等穩定性能力，這類能力適合承擔渠道層面的故障切換，應用層可以把精力放在業務兜底上。不過，網關的降級觸發條件、返回的錯誤碼和錯誤體格式與官方是否完全一致，需要以平臺文檔和實際測試爲準。業務介紹中提到的“不限併發”也不等於永遠不會出現 429，上游模型本身的限制依然存在。穩妥的做法是：應用層始終保留對 429、5xx 的處理邏輯，並在網關整體不可達時有自己的兜底方案。
🎯 技術建議：接入網關後，建議先在測試環境故意觸發幾類錯誤，比如使用錯誤密鑰、請求不存在的模型名、發送超長上下文，記錄 API易 apiyi.com 實際返回的狀態碼與錯誤體字段，再據此調整應用層的錯誤分類規則，而不是照搬官方文檔的錯誤格式。
常見問題 FAQ
Q1：AI API 報 429 和報 500 有什麼本質區別？
429 表示你的請求超出了限額，問題在調用方的節奏或賬戶額度；500 表示服務端出錯，問題在上游。前者應該先降速、遵守等待時間，後者可以有限次重試，持續失敗再降級。兩者都可能“等一會兒就好”，但處理重點不同。
Q2：爲什麼 401 錯誤絕對不要自動重試？
401 是確定性錯誤，密鑰不對時重試一萬次結果都一樣。自動重試不僅浪費資源，還會掩蓋問題，讓告警延遲。正確做法是立即中斷，檢查密鑰內容、環境變量注入和請求地址是否匹配。
Q3：429 一直重試都不恢復，可能是什麼原因？
最常見的原因是額度或餘額耗盡。部分服務商這種情況也返回 429，但錯誤體中的類型字段與普通限流不同。另一種可能是你的重試沒有加隨機抖動，大量請求同時重發，持續打滿限額。建議先看錯誤體，再檢查重試的時間分佈。
Q4：多模型降級會不會影響輸出質量？
可能會。降級本質上是用可用性換質量，所以要在業務層面明確哪些場景可以接受降級。建議爲備用模型準備獨立驗證過的提示詞，並在監控中統計降級比例。如果降級比例長期偏高，就該檢查主模型的配額和穩定性了。
Q5：如何低成本測試不同模型的降級鏈路？
可以藉助支持多模型統一接口的平臺搭建測試環境。比如通過 API易 apiyi.com 用同一套 OpenAI 兼容調用方式切換不同廠商的模型，只需修改模型名，就能驗證主備模型在相同提示詞下的輸出差異和報錯表現，適合在上線前跑一遍降級演練。
Q6：使用了帶自動降級的網關，應用層還需要熔斷嗎？
需要。網關的降級解決的是上游渠道問題，但網關本身也可能出現網絡不通或整體不可用。應用層的熔斷與兜底就是爲這種情況準備的。使用 API易 這類網關時，可以把應用層熔斷的統計對象設爲“網關整體”，而不是單個模型渠道，兩層職責就不會重複。
Q7：重試、降級和熔斷有哪些已知的副作用？
重試可能產生重複計費，在非冪等場景（如帶工具調用的寫操作）中可能導致動作重複執行。降級可能帶來質量波動和輸出格式差異。熔斷參數設得過敏會誤拒正常請求。因此三者都需要配合監控指標持續調參，不能配置一次就不管。
AI API 錯誤處理核心要點 Key Takeaways
- 先分類再處理：確定性錯誤立即修正，暫時性錯誤才進入重試流程。
- 429 要看錯誤體：區分速率限制和額度耗盡，後者重試沒有意義。
- 401 永不重試：直接告警，重點排查密鑰、環境變量和接口地址是否匹配。
- 重試要有上限：指數退避加隨機抖動，設置次數和總耗時雙重預算。
- 降級要能力對齊：備用模型需支持相同特性，並配套獨立提示詞。
- 熔斷只算服務端錯誤：5xx 和超時計入失敗率，客戶端錯誤不計入。
- 網關與應用分工：可藉助 API易 apiyi.com 處理渠道層容錯，應用層負責業務兜底。
總結
AI API 報 429、401、500 時，最重要的是放棄“統一重試”的習慣，改爲按錯誤性質分別處理：
- 限流類錯誤：遵守
Retry-After，用指數退避加抖動重試，同時從源頭控制併發和 token 用量。 - 認證與請求類錯誤：立即中斷、告警、修配置，絕不自動重試，也不要用降級掩蓋。
- 服務端錯誤：有限次重試，持續失敗時切換備用模型，高併發場景配合熔斷器快速止損。
- 網關與應用分層：網關處理渠道切換與負載，應用層掌握業務語義、重試預算和最終兜底。
建議先把本文的決策表整理成團隊內部的錯誤處理規範，再按規範做一次故障演練，確認每類錯誤都能走到預期的分支。
如果你正在規劃多模型的降級鏈路，可以通過 API易 apiyi.com 在統一接口下對比多個模型的表現和報錯行爲，先在測試環境驗證容錯策略，再上線到生產。
📚 參考資料
- Ofox.ai Blog – AI API Error Handling 主題文章：介紹 429 限流、401 認證、500 服務端錯誤的處理思路，以及指數退避、多模型降級與熔斷器
- 鏈接：
ofox.ai/blog/page/41/ -
說明：本文選題方向的參考來源，適合對照閱讀英文資料
-
Ofox.ai Blog – LLM API Gateway 相關文章：討論 LLM 網關選型與多服務商故障的背景
- 鏈接：
ofox.ai/blog/page/40/ -
說明：瞭解網關層容錯能力在多模型架構中的位置
-
API易 文檔中心：平臺接入說明與使用文檔
- 鏈接：
docs.apiyi.com - 說明：錯誤碼格式、降級行爲等細節請以平臺文檔和實際測試爲準
作者：APIYI 技術團隊
技術交流：歡迎在 API易 網站首頁聯繫我們交流 AI API 穩定性實踐，更多接入資料可查閱 docs.apiyi.com 文檔中心
