作者注：按錯誤碼給模型 API 報錯分診，講清楚何時重試、何時切換備用模型、何時停下來修配置，並附錯誤碼分診表、備用模型覈對表和上線檢查清單。
模型 API 報錯後，先看是哪一類錯誤，再決定怎麼處理。4xx 多數是請求或配置的問題，重試不會讓它變好；5xx、529 和超時才值得做有限重試，重試仍失敗再切換備用模型；沒有冪等保證的請求，不要自動重試。重試不是默認動作，切換也解決不了所有問題。很多線上事故並不是模型掛了，而是錯誤處理邏輯把一次小故障放大成了重複扣費、重複寫庫和整條鏈路被限流。
這篇不是錯誤碼字典的翻譯。它面向已經把模型 API 接進生產或半生產環境的開發者，重點是出錯時怎樣避免把局面弄得更糟。讀完你會拿到一張錯誤碼分診表、一套重試與回退策略、一張備用模型能力覈對表，以及一份可以照着執行的上線前檢查清單。全文可以濃縮成一句判斷：4xx 先修，5xx 才談重試，非冪等請求先停手。
模型 API 報錯的 5 類分診：先分錯，再決定重試或切換
結論先說：模型 API 報錯只分五類，每一類的處理方向基本固定。把錯誤碼先歸到類別裏，後面的重試和切換邏輯就不會亂。
| 錯誤類別 | 典型狀態碼 | 根因位置 | 默認動作 |
|---|---|---|---|
| 請求錯 | 400、404、409、422 |
你的請求體、參數、模型 ID、端點 | 不重試，修請求 |
| 鑑權錯 | 401、403 |
Key、請求頭、權限、地區或策略 | 不重試，查 Key 和權限 |
| 額度或限流 | 402、429 |
餘額、併發、速率、模型額度 | 402 停手；429 看錯誤體再退避或切換 |
| 上游故障 | 500、502、503、529 |
網關、上游服務、過載 | 有限重試，失敗後切換 |
| 超時或流中斷 | 408、504、網絡超時、流斷開 |
鏈路、長輸出、上游響應慢 | 先確認是否已執行或已計費，冪等才重試 |
5 類錯誤分診的關鍵：區分“重試”和“切換”
重試指用同一個模型、同一條線路再發一次請求，適合解決瞬時抖動；切換指換模型或換線路，適合解決某個上游持續不可用。兩者的代價不一樣：重試的代價是延遲和可能的重複計費，切換的代價是輸出質量、工具調用兼容性和成本都可能發生變化。
所以分診的順序固定爲三步：先確認錯誤類別，再判斷請求是否冪等，最後選擇重試、切換或停手。跳過第二步最危險，因爲一個已經執行過的工具調用再執行一次，帶來的就不只是“多花點錢”了。
爲什麼“全部重試”會讓模型 API 報錯更嚴重
結論：對所有錯誤一律重試，看起來穩妥，實際上會同時放大成本、副作用和限流。生產環境裏，這類邏輯造成的事故往往比原始錯誤更難排查。
第一個問題是重複扣費。流式響應中斷不一定說明請求失敗，上游可能已經生成了一部分 token，這部分費用可能已經產生。盲目重放等於同一個任務付兩次錢，長輸出任務尤其明顯。
第二個問題是重複執行。Agent 場景裏，一次模型請求可能觸發寫庫、發消息、創建任務甚至支付。如果工具調用階段超時，你並不知道工具是否已經執行；這時直接重放整個請求，很可能出現兩條訂單、兩封郵件。
第三個問題是限流雪上加霜。429 本身就是上游在說“慢一點”，這時客戶端立刻併發重試，相當於主動加壓。更常見的反例是對所有 4xx 都重試：401 本來是 Key 寫錯，重試幾輪後請求量被打滿，最後日誌裏看到的是一堆 429，真正的根因反而被掩蓋了。
401、429、500、529 錯誤碼分診表：哪些重試，哪些切換
結論：下表覆蓋生產中最常見的 14 個狀態碼，其中只有少數值得重試，切換的前提是重試已經確認無效。表中的“是否切換”指換備用模型或線路，具體含義以實際錯誤體和各家文檔爲準。
| 狀態碼 | 常見含義 | 是否重試 | 是否切換 | 處理動作 |
|---|---|---|---|---|
400 |
請求格式或參數錯誤 | 否 | 否 | 修請求體，檢查字段和類型 |
401 |
Key 無效或鑑權失敗 | 否 | 否 | 查 Key、Authorization 請求頭、Base URL |
402 |
餘額不足或額度用完 | 否 | 視情況換線路 | 充值或切到有額度的線路，並告警 |
403 |
權限、地區或策略拒絕 | 否 | 否 | 查賬號權限、模型授權、地區限制 |
404 |
模型或端點不存在 | 否 | 否 | 覈對模型 ID 和端點路徑 |
408 |
請求超時 | 冪等時有限重試 | 可選 | 確認未執行後重試 1 次 |
409 |
衝突或狀態不一致 | 否 | 否 | 查業務狀態，避免併發寫 |
422 |
參數校驗失敗 | 否 | 否 | 修參數，常見於結構化輸出 schema |
429 |
限流、併發或額度 | 退避後重試 | 重試失敗可切換 | 先讀錯誤體和 Retry-After |
500 |
上游內部錯誤 | 有限重試 | 連續失敗則切換 | 記錄 request id 和錯誤體 |
502 |
網關錯誤 | 有限重試 | 可切換 | 區分網關問題和上游問題 |
503 |
服務不可用 | 有限重試 | 可切換 | 尊重 Retry-After，必要時降級 |
504 |
網關超時 | 冪等時才重試 | 可切換 | 先查任務是否已執行 |
529 |
上游過載 | 有限重試 | 可切換 | 退避加抖動，持續過載就切換 |
429 不一定是限流：讀錯誤體再決定
429 最容易被誤判。它可能表示速率限流，也可能是併發超限、模型額度耗盡，個別情況下還和餘額有關。速率限流通常退避幾秒就能恢復；額度耗盡時，重試多少次都沒用，直接切到最貴的模型更是隻讓成本翻倍，問題依舊。
處理 429 的步驟如下：
- 讀取響應頭裏的
Retry-After，有就按它等待。 - 讀取錯誤體裏的錯誤類型字段，區分 rate limit、concurrency 和 quota。
- 速率或併發問題：退避重試 1 到 2 次，並降低本地併發。
- 額度問題：停止重試，告警並切換到有額度的線路。
500 的思路類似。它不一定說明模型本身壞了，可能是網關，也可能是上游。先記下 request id 和錯誤體摘要，排查和對賬都要用到。
模型 API 報錯重試策略：次數、退避、Retry-After 與冪等
結論：重試只針對瞬時錯誤，次數控制在 1 到 2 次，必須帶指數退避和隨機抖動，並且只對冪等請求自動執行。不滿足這四個條件，就不要自動重試。
| 參數 | 建議值 | 說明 |
|---|---|---|
| 可重試錯誤 | 429、500、502、503、504、529、網絡超時 |
4xx 中只有 408、429 例外 |
| 最大重試次數 | 1-2 次 | 超過後進入切換或告警，不再原地打轉 |
| 退避間隔 | 1s、2s、4s 指數遞增 | 每次疊加隨機抖動，避免多實例同時重試 |
| Retry-After | 有就優先遵守 | 優先級高於本地退避算法 |
| 冪等前提 | 必須滿足 | 寫操作、工具調用、發消息、支付默認不自動重試 |
重試策略落地步驟
- 建立錯誤分類函數。輸入狀態碼和錯誤體，輸出五類之一，其他邏輯都基於這個分類結果，不要在業務代碼裏到處判斷數字。
- 給請求打冪等標籤。純文本生成、摘要、翻譯通常可以視爲冪等；只要請求會觸發工具或產生外部寫操作，就標記爲非冪等。
- 非冪等請求先查狀態。工具調用超時後，先查詢任務或數據庫狀態，確認沒有執行過再重試，必要時使用業務側的冪等鍵去重。
- 設置總時長上限。每個請求的重試總耗時要有上限，否則用戶側請求早就超時了，後臺還在重試。
- 記錄每一次嘗試。至少記錄 request id、模型 ID、狀態碼、錯誤類、延遲、token 用量和重試次數。
最後一步經常被省略，但對賬和排錯都離不開它。如果通過 API易 apiyi.com 接入，控制檯裏可以按 Key 查看用量和調用日誌，把本地記錄的 request id 和平臺側的錯誤信息對上，就能判斷一次失敗究竟發生在網關、上游，還是你自己的請求體。
流中斷單獨處理。流式請求斷開時，先看已經收到多少 token、內容是否已經可用，再決定是續寫、丟棄還是重放。長輸出任務重放前要想清楚：前一次的生成可能已經計費。
🎯 排錯建議：遇到
500、529這類不好判斷歸屬的錯誤，先保存錯誤體原文和 request id，再到 API易 apiyi.com 控制檯覈對同一時段的用量與日誌。不要只憑狀態碼就下結論。
切換備用模型策略：能力分層、模型映射與兼容覈對
結論：切換的前提是備用模型已經提前確認能接住同樣的任務。如果故障發生時才第一次走回退路徑，大概率會出現第二次故障。
先給模型分層：旗艦、通用、輕量。每類任務映射到一個主模型和一個同層或相鄰層的備用模型。不要所有請求都回退到最貴的模型，那樣一次上游抖動就可能讓賬單失控，而且不少簡單任務換到旗艦模型上也沒有收益。
| 能力項 | 主模型 | 備用模型 | 是否兼容 | 切換前要做什麼 |
|---|---|---|---|---|
| 上下文窗口 | 填寫實際上限 | 填寫實際上限 | 待覈對 | 確認最長真實輸入能裝下，否則先做截斷策略 |
| 工具調用 | 工具 schema、並行調用 | 同上 | 待覈對 | 驗證調用 ID 回傳格式和參數結構 |
| 結構化輸出 | JSON schema 或嚴格 JSON | 同上 | 待覈對 | 用同一 schema 跑通過率，防止 422 |
| 多模態輸入 | 圖片、音頻、視頻 | 同上 | 待覈對 | 確認輸入格式和大小限制 |
| reasoning 參數 | 推理檔位或思考字段 | 同上 | 待覈對 | 不支持的參數要在切換時剔除或映射 |
| 價格與限流 | 以控制檯爲準 | 以控制檯爲準 | 待覈對 | 估算切換後的成本，確認限額夠用 |
| 地區與合規 | 允許範圍 | 允許範圍 | 待覈對 | 確認備用線路在業務允許的地區和合規範圍內 |
這張表建議每個任務類型填一份，“是否兼容”一列只填驗證過的結果，不要憑印象填寫。reasoning 參數最容易出問題：主模型支持的推理檔位字段，換到備用模型上可能直接返回 400 或 422。切換邏輯裏要有一層參數適配，而不是原樣轉發。
模型映射：模型 ID 以控制檯爲準
切換時最常見的低級錯誤是模型 ID 寫錯，結果拿到 404。建議維護一張“邏輯模型名到實際模型 ID”的映射表，業務代碼只引用邏輯名。通過 API易 apiyi.com 調用時，各模型的準確 ID、可用狀態和價格都以控制檯和文檔爲準，接入方式統一使用 https://api.apiyi.com/v1 作爲 base_url。映射表變更後，跑一次金絲雀請求再發布。
備用模型驗證與多模型網關：金絲雀、日誌和自動降級
結論：備用模型上線前要用真實任務驗證；回退之後要驗收輸出，不能只看狀態碼是不是 200。多模型網關可以降低切換成本，但不能替你做質量驗收。
備用模型驗證三步走
- 金絲雀請求。選一組真實業務任務，同一提示、同一工具、同一輸入，分別發給主模型和備用模型。
- 同題對比。比較通過率、延遲、首 token 時間、token 成本和失敗率。工具調用類任務還要逐項覈對調用 ID、參數結構和返回結構是否兼容。
- 回退後驗收。真實切換髮生後，對輸出做自動校驗，例如 JSON 能否解析、必填字段是否齊全、工具參數是否合法，並記錄切換原因和驗收結果。
回退路徑要定期演練。可以每週人爲把一小部分流量切到備用模型，確認鏈路仍然可用，避免依賴、參數或模型 ID 在不知不覺中失效。
日誌字段建議至少包括：
- 請求 ID、模型 ID、端點、狀態碼、錯誤類、錯誤體摘要
- 延遲、首 token 時間、總耗時、重試次數、切換目標
- 輸入 token、輸出 token、緩存命中、估算費用
- 工具調用名稱、調用 ID、是否執行成功
- 切換原因、切換後是否通過驗收
多模型網關在容災裏的作用
自己對接多家廠商做容災，至少要維護多套 Key、多套 SDK 和多套錯誤格式。用 API易 apiyi.com 這類聚合網關，一個 Key 就能調用 OpenAI、Claude、Gemini、DeepSeek、Qwen 等主流模型，接口兼容 OpenAI 標準，也支持 Claude、Gemini 原生格式。主備模型可以放在同一套接入代碼裏，切換時改的是模型 ID，而不是整條集成鏈路。
平臺側還提供多節點部署、智能路由、自動降級和負載均衡，可以吸收一部分上游抖動。不過網關層的自動降級不能替代業務層的判斷：冪等檢查、工具調用去重、輸出驗收，仍然要在你自己的代碼裏完成。比較穩妥的分工是：網關負責線路和節點層面的可用性，應用負責任務層面的正確性。
💡 容災建議：設計主備模型時，可以先在 API易 apiyi.com 用同一個 Key 對主模型和備用模型跑同一組金絲雀任務，再把驗證通過的組合寫進模型映射表。新用戶可以先用免費測試額度做驗證。
模型 API 報錯常見問題 FAQ
結論：下面五個問題覆蓋了生產中爭議最多的場景，回答都遵循同一個原則：先判斷，再動作。
Q1:401 要不要重試？
不要。`401` 表示鑑權失敗，重試只會增加請求量，甚至把問題變成 `429`。檢查 Key 是否有效、`Authorization` 請求頭格式是否正確、Base URL 是否和 Key 屬於同一平臺。使用 API易 apiyi.com 時，可以到控制檯確認 Key 狀態。
Q2:429 要不要馬上換模型？
不建議馬上換。先讀錯誤體和 `Retry-After`：速率或併發限流，退避後重試 1 到 2 次通常就能恢復；額度耗盡時才切換線路。切換時選同層級的備用模型，不要一律切到最貴的模型。
Q3：流式輸出中斷，要不要重放？
先別急着重放。流中斷不等於請求失敗，可能已經生成內容併產生費用。先看已收到的 token 數量和內容是否可用：可用就保留或續寫；不可用且請求冪等，再重放 1 次。實際計費以控制檯用量爲準。
Q4：工具調用出現重複執行怎麼辦？
根本做法是在工具層做冪等，用業務側的冪等鍵或任務 ID 去重，同一 ID 只執行一次。工具調用超時後，先查任務狀態，確認沒有執行再重試。已經出現重複的，按調用 ID 回溯日誌，補償或撤銷多出來的操作。
Q5：切換備用模型後返回 200，但結果不對怎麼辦？
200 只說明請求成功，不代表任務成功。對輸出做自動校驗，例如 JSON 結構、必填字段、工具參數合法性。校驗失敗要計入失敗率，並觸發告警或人工複覈。如果某個備用組合頻繁驗收失敗，就從映射表裏撤下，重新跑金絲雀驗證。
上線前檢查清單與總結：什麼時候重試、切換、停手
結論：上線前逐項覈對下面這張清單，比故障發生後臨時補邏輯可靠得多。記住那句判斷：4xx 先修，5xx 才談重試，非冪等請求先停手。
| 序號 | 檢查項 | 通過標準 |
|---|---|---|
| 1 | 先判斷錯誤類型 | 所有狀態碼都能歸入五類之一，未知錯誤默認不重試 |
| 2 | 4xx 不自動重試 | 400、401、402、403、404、409、422 直接告警或修復 |
| 3 | 再決定重試或切換 | 只對瞬時錯誤重試，最多 1 到 2 次，帶退避和抖動 |
| 4 | 尊重 Retry-After | 響應頭存在時優先按它等待 |
| 5 | 冪等檢查 | 工具調用、寫操作、發消息、支付默認停手，查狀態後再決定 |
| 6 | 流中斷處理 | 先看已收 token 和費用，不盲目重放 |
| 7 | 備用模型覈對 | 能力覈對表已按任務類型填寫並驗證 |
| 8 | 模型映射 | 邏輯名到模型 ID 的映射與控制檯一致 |
| 9 | 最後驗收輸出 | 切換後做結構和字段校驗，不只看 200 |
| 10 | 日誌與演練 | 關鍵字段齊全，回退路徑定期演練 |
模型 API 報錯處理 Key Takeaways
- 什麼時候重試：
429、500、502、503、529和冪等的超時請求，有限次數並退避。 - 什麼時候切換：重試仍失敗、上游持續不可用或額度耗盡，且備用模型已驗證。
- 什麼時候停手：
401等 4xx 配置錯誤，以及狀態不明的非冪等請求。 - 切換不等於成功：備用模型返回 200 後仍要驗收輸出。
- 網關和應用分工：線路可用性交給網關，任務正確性留在業務代碼。
錯誤處理做得好不好，看的不是重試寫得多積極，而是能否在每次報錯時做對判斷。建議先把錯誤分類、冪等標籤和日誌字段補齊，再逐步引入備用模型。備用線路可以考慮 API易 apiyi.com：一個 Key 覆蓋多家主流模型，便於用同一套代碼完成主備驗證與切換，價格和可用性以控制檯和文檔爲準。
📚 參考資料
- API易 文檔中心：接入方式、模型列表與計費說明
- 鏈接：
docs.apiyi.com -
說明：模型 ID、價格和可用性以文檔與控制檯爲準
-
HTTP 狀態碼語義說明：
Retry-After等標準響應頭的含義 - 鏈接：
developer.mozilla.org/docs/Web/HTTP/Status - 說明：用於理解 4xx、5xx 的通用語義，具體含義以各模型平臺錯誤體爲準
作者：APIYI 技術團隊
技術交流：歡迎在 API易 官網 apiyi.com 首頁聯繫我們，更多接入資料可訪問 docs.apiyi.com 文檔中心
