作者注：遇到 429 不必馬上換模型。本文用 3 步排查判斷限流來自上游廠商、網關還是免費檔，並給出指數退避、Retry-After 與故障切換的配置方法。
凌晨跑批任務時日誌突然刷出一屏 429 Too Many Requests，很多人的第一反應是“這個模型不行，趕緊換一個”。這個判斷往往下得太早。429 只說明“有人限制了你”，沒有說明是誰限制的，也沒有說明限制的維度是什麼。本文的核心觀點是 先定位限流來源，再決定退避還是切換。
這不是一篇泛泛而談的重試科普。我們會按照真實排查順序，拆解錯誤信息、響應頭和限流維度，再給出退避參數與故障切換鏈路的配置建議。
核心價值：讀完本文，你能在幾分鐘內判斷一次 429 來自上游廠商、中間網關還是免費檔配額，併爲自己的應用配好一套“該等就等、該切就切”的容錯策略。
429 限流判斷核心要點
429 是 HTTP 標準裏的“請求過多”狀態碼。在大模型 API 場景中，它可能由調用鏈上任意一層返回。下表總結了最常見的三類來源，以及每一類對應的正確處理方式。
| 限流來源 | 典型特徵 | 是否該換模型 | 推薦處理 |
|---|---|---|---|
| 上游模型廠商 | 錯誤體帶廠商自己的錯誤類型與措辭，響應頭帶廠商限流字段 | 通常不需要 | 按 Retry-After 退避，必要時降低併發或申請提額 |
| 中間網關/聚合平臺 | 錯誤措辭來自網關，提示賬戶級或分組級速率 | 不需要 | 檢查網關側配額與併發設置，或切換網關分組 |
| 免費檔/試用額度 | 提示免費額度、每日次數或容量不足 | 視情況 | 升級付費檔，或切換到有容量的同類模型 |
爲什麼 429 不等於模型掛了
模型本身不可用時，更常見的信號是 5xx 系列錯誤。例如 Anthropic 的過載會返回 529 overloaded_error，網關或負載均衡異常常見 502、503。這些狀態碼說明服務端暫時處理不過來，和“你的賬號超過了配額”是兩回事。
429 則帶有明確的歸屬含義：限流規則針對的是你，可能是你的 API Key、你的組織、你所在的免費檔，或者網關給你分配的速率。換一個模型有時能繞過去，但如果限流來自網關賬戶級配額，換模型照樣會撞牆。如果限流來自上游廠商的每分鐘 token 上限，等幾秒就能恢復，換模型反而引入了輸出質量的不確定性。
第三方對 Claude Code 的排障整理也印證了這一點：Claude Code 遇到 429 時會顯示 Request rejected (429)，後面附上服務端原話，而正是這段原話告訴你限流來自 Anthropic、來自網關，還是來自免費檔。所以排查的第一步永遠是讀完整的錯誤信息，而不是隻看狀態碼。
429 與相鄰狀態碼的區別
爲了避免把不同錯誤混爲一談，下表列出了在大模型調用中容易與 429 混淆的幾個狀態碼。
| 狀態碼 | 含義 | 責任方 | 是否適合重試 | 是否適合故障切換 |
|---|---|---|---|---|
| 429 | 請求過多，觸發速率或配額限制 | 調用方額度 | 適合，需退避 | 退避無效後再切 |
| 529 | 上游過載（Anthropic 特有） | 服務端容量 | 適合，短暫退避 | 適合 |
| 503 | 服務暫不可用 | 服務端或網關 | 適合 | 適合 |
| 500/502 | 內部錯誤或網關錯誤 | 服務端或網關 | 有限次重試 | 適合 |
| 400/401/403 | 參數、鑑權或權限問題 | 調用方配置 | 不適合 | 不適合，需修配置 |
這張表裏有一個容易被忽略的細節：Claude Code 的 fallbackModel 機制據第三方測試只在 529 過載時觸發，最多嘗試 3 個備用模型，而不是在 429 時觸發。這說明工具設計者本身也認爲，429 的第一反應應該是退避，而非換模型。
如何判斷 429 限流來自誰：3 步排查
下面是一套可以直接照做的 429 排查流程。三步按成本從低到高排列，大部分情況在第一步就能定位。
第 1 步：讀完整的 429 錯誤體
不要只在日誌裏記錄狀態碼，要把響應體原樣記錄下來。不同層返回的 429 在措辭上差異明顯，這是最直接的線索。
- 上游廠商返回：錯誤體裏通常帶有廠商的錯誤類型字段，例如 Anthropic 會給出
rate_limit_error類型，OpenAI 風格接口會給出rate_limit_exceeded一類的錯誤碼，並說明是請求數還是 token 數超限。 - 網關返回：措辭往往提到“賬戶”“分組”“令牌”“渠道”等網關自身概念，或者明確寫出網關名稱。
- 免費檔返回：會出現“free tier”“quota”“daily limit”“capacity”等字樣。第三方對某些模型免費試用的測試中，就頻繁遇到這種容量型 429。
如果你通過中轉或聚合平臺調用，要特別留意網關是否把上游原始錯誤透傳了出來。透傳說明上游在限你，非透傳的自定義措辭則說明是網關在限你。
第 2 步：檢查 429 響應頭
響應頭是第二條證據鏈。主流廠商會在響應頭裏返回剩餘額度與重置時間，網關也可能附帶自己的字段。
| 響應頭 | 常見來源 | 含義 | 排查用途 |
|---|---|---|---|
Retry-After |
HTTP 標準，多方通用 | 建議等待的秒數 | 退避時優先採用 |
x-ratelimit-remaining-requests |
OpenAI 風格接口 | 當前窗口剩餘請求數 | 判斷是否爲 RPM 限流 |
x-ratelimit-remaining-tokens |
OpenAI 風格接口 | 當前窗口剩餘 token 數 | 判斷是否爲 TPM 限流 |
anthropic-ratelimit-requests-remaining |
Anthropic | 剩餘請求數 | 確認限流來自 Anthropic |
anthropic-ratelimit-input-tokens-remaining |
Anthropic | 剩餘輸入 token 數 | 判斷是否爲輸入 token 限流 |
判斷規則很簡單：出現廠商前綴的限流頭並且剩餘值爲 0，基本可以確定是上游廠商在限你；沒有任何廠商限流頭，只有網關自定義字段或乾脆什麼都沒有，則網關層的可能性更大。需要注意的是，部分廠商近年來把具體限額改爲只在控制檯展示，響應頭裏的信息可能不完整，這時要回到第 1 步的錯誤措辭和第 3 步的維度對比。
第 3 步：對照限流維度
知道是誰在限你之後，還要弄清楚限的是什麼。不同廠商的限流規則並不統一，第三方對 5 家廠商的橫向整理顯示：Anthropic 主要按每分鐘 token 數限制，且緩存命中的 token 不計入限額；DeepSeek 主要限制併發數；OpenAI 和 Google 的具體額度則更多放在控制檯裏查看。
這對配置策略有直接影響，常見對應關係如下：
- RPM（每分鐘請求數）超限：把多個小請求合併成批量請求，或者在客戶端加令牌桶勻速發送。
- TPM（每分鐘 token 數）超限：縮短上下文、啓用提示緩存，長文檔任務拆分到不同時間窗口。
- 併發數超限：降低 worker 數量，用隊列控制同時在途的請求數，單純退避作用有限。
- 日配額或免費額度耗盡：退避沒有意義，只能等重置、升級檔位或切換到其他渠道。
第 4 種情況是唯一一種“退避註定無效”的 429，也是最應該儘早識別並直接進入故障切換的情況。
429 退避策略怎麼配
確認 429 屬於可恢復的速率限流後，就進入退避階段。退避的目標不是“儘快重試”，而是“在不加重擁堵的前提下儘快恢復”。
指數退避加隨機抖動
最常用的方案是指數退避（Exponential Backoff）加隨機抖動（Jitter）。第 n 次重試的等待時間約爲“基礎延遲 × 2 的 n 次方”，再在此基礎上疊加一個隨機量，並設置上限。隨機抖動的作用是打散多個客戶端的重試時間點，避免它們在同一秒集中衝擊，形成“重試風暴”。
如果響應裏帶有 Retry-After，它的優先級應高於你自己算出來的退避時間。服務端比你更清楚窗口何時重置，按它的建議等待，往往是最快恢復的方式。
退避參數推薦值
下表給出一組適用於大多數對話與批處理場景的起步參數，實際使用時可按業務延遲容忍度調整。
| 參數 | 推薦起步值 | 說明 |
|---|---|---|
| 基礎延遲 | 1 秒 | 第一次重試前的等待時間 |
| 退避倍數 | 2 | 每次重試等待時間翻倍 |
| 最大單次等待 | 30-60 秒 | 防止等待時間無限增長 |
| 最大重試次數 | 3-5 次 | 超過後進入故障切換或報錯 |
| 隨機抖動 | 等待時間的 0-100% 隨機 | 推薦“全抖動”方式，打散重試 |
| Retry-After | 有則優先 | 覆蓋自算的退避時間 |
有兩個配置細節經常被忽略。第一，交互式場景（例如聊天界面）總等待時間不宜過長，建議設置一個總超時預算，超出後直接走切換或提示用戶。第二，不要對 400、401、403 這類配置錯誤做退避重試，它們再等多久也不會自己變好，只會白白消耗時間和配額。
如果你使用的是官方 SDK，許多 SDK 已經內置了針對 429 和 5xx 的自動重試，通常通過 max_retries 一類的參數控制次數。在自己再包一層重試之前，先確認 SDK 默認行爲，避免兩層重試疊加導致實際重試次數成倍放大。
429 故障切換怎麼配
退避是“原地等待”，故障切換（Failover）是“換條路走”。兩者不是二選一，而是先後關係：先退避，退避無效再切換。
什麼時候觸發故障切換
建議在以下任一條件滿足時觸發切換，而不是一見 429 就切：
- 達到最大重試次數，429 仍然持續返回；
- 錯誤措辭明確指向日配額、免費額度耗盡或“容量不足”；
Retry-After給出的等待時間超過了業務能接受的上限；- 同一渠道在短時間內連續多次失敗，觸發熔斷閾值。
第三方對 OpenRouter 上某熱門模型頻繁 429 的處理建議也是同樣的思路：先退避，再故障切換到同一接口下的其他模型。這樣的順序既能喫到原模型的輸出質量，也能保證服務不中斷。
切換鏈路的三種設計
故障切換的“備用路線”有不同層次，切換代價從低到高依次爲：
- 同模型換渠道：同一個模型，換另一個 API Key、另一個分組或另一家供應商。輸出一致性最好，是首選。
- 同廠商換檔位：例如從旗艦模型降到同系列的輕量模型，能力略降但風格接近。
- 跨廠商換模型：換到另一家的同級模型，可用性最高，但提示詞效果和輸出格式需要提前驗證。
在此之上建議加一層熔斷器（Circuit Breaker）：某條渠道連續失敗達到閾值後，在一段冷卻時間內直接跳過它，冷卻結束後放少量探測請求，恢復了再逐步放量。這能避免每個請求都先撞一次牆再切換，顯著降低整體延遲。
上圖對比的兩種策略，在實際項目裏可以通過同一個統一接口完成驗證。像 API易 這類兼容 OpenAI 與 Anthropic 接口格式的平臺，同一套代碼只需修改 model 參數即可切換備用模型，比爲每家廠商分別維護 SDK 要省事得多。
429 限流處理快速上手
下面把前面的內容整理成一份可以直接對照落地的配置清單。全文不涉及代碼，你可以把它當作代碼評審或運維配置時的檢查表。
5 項配置檢查清單
- 日誌：記錄完整響應體與響應頭，至少包含狀態碼、錯誤類型、錯誤措辭、
Retry-After以及各類ratelimit字段。 - 分類：在客戶端把錯誤分爲“可退避”（429 速率類、529、503）、“需切換”（配額耗盡、持續失敗）、“不可重試”（400、401、403）三類。
- 退避：按上文參數表配置指數退避加全抖動，
Retry-After優先，並設置最大重試次數與總超時預算。 - 切換鏈：按“同模型換渠道 → 同廠商換檔位 → 跨廠商換模型”的順序配置備用列表，提前驗證每個備用模型的提示詞效果。
- 熔斷與告警：爲每條渠道設置失敗閾值與冷卻時間，同時對 429 比例設置告警，持續偏高時說明需要申請提額或調整併發。
備用模型鏈路示例
下表是一個常見的三級切換鏈路示意。具體模型名以平臺模型列表爲準，涉及的計費請以價格頁爲準，本文不列具體單價。
| 層級 | 選擇思路 | 接口格式 | 可用平臺 | 價格口徑 |
|---|---|---|---|---|
| 主用 | 業務效果最好的旗艦模型 | OpenAI 或 Anthropic 格式 | API易 apiyi.com、官方 API | 以 docs.apiyi.com/models 爲準 |
| 一級備用 | 同模型的另一渠道或分組 | 與主用一致 | API易 apiyi.com、官方 API | 以 docs.apiyi.com/models 爲準 |
| 二級備用 | 同廠商輕量模型或跨廠商同級模型 | OpenAI 兼容格式 | API易 apiyi.com 等聚合平臺 | 以 docs.apiyi.com/models 爲準 |
接入方式上，如果你使用 OpenAI 或 Anthropic 官方 SDK，通常只需要把 base_url 改成平臺提供的地址、api_key 換成平臺密鑰即可。具體的接口地址和各模型的調用說明，建議以 API易 文檔中心 docs.apiyi.com 爲準，不要照搬網上未經覈實的地址。
🚀 快速開始：搭建 429 容錯鏈路時，建議先通過 API易 apiyi.com 用同一套代碼接入主用和備用模型。平臺提供本文涉及的主流模型 API 調用，兼容 OpenAI 與 Anthropic 接口格式，切換模型只需改
model參數。接入文檔見 docs.apiyi.com，各模型輸入輸出單價、緩存價格與計費口徑以價格頁 docs.apiyi.com/models 的實際數據爲準。
常見問題 FAQ
Q1：什麼是 429 限流？
429 是 HTTP 標準中的 Too Many Requests 狀態碼，表示調用方在某個時間窗口內超過了允許的請求數、token 數、併發數或總配額。它說明的是“你被限制了”，並不說明模型本身故障。
Q2：429 和 529、503 有什麼區別？
429 指向調用方的額度問題，責任在“你用得太多”；529 是 Anthropic 的過載錯誤，503 是服務暫不可用，責任都在服務端容量。前者優先退避和調整用量，後兩者更適合短暫退避後直接故障切換。
Q3：怎樣最快判斷 429 來自上游廠商還是網關？
先看錯誤體措辭：帶廠商錯誤類型的通常來自上游，提到賬戶、分組、渠道等概念的通常來自網關。再看響應頭：出現廠商前綴的 `ratelimit` 字段且剩餘值爲 0，基本可以確認是上游在限流。
Q4：爲什麼退避了很多次 429 還是不恢復？
最常見的原因是限流維度判斷錯了。如果是日配額或免費額度耗盡，退避註定無效；如果是併發數超限，客戶端仍在高併發發送，退避也只能緩解。此時應降低併發或直接進入故障切換。
Q5：如何快速搭建一套多模型故障切換鏈路？
推薦使用支持多模型統一接口的平臺進行驗證：
1. 在 API易 apiyi.com 註冊賬號並獲取 API Key；
2. 按 docs.apiyi.com 文檔配置 `base_url`，使用 OpenAI 或 Anthropic 格式接入；
3. 在客戶端配置主用與備用模型列表，通過修改 `model` 參數實現切換。
這樣主用和備用模型共用一套代碼，切換鏈路的測試成本會低很多。
Q6：故障切換會不會讓成本失控？
有可能。備用模型的單價、上下文長度和緩存策略都可能與主用模型不同，頻繁切換會改變賬單結構。建議爲每個備用模型提前核對價格，統一以 API易 價格頁 docs.apiyi.com/models 的實際數據爲準，並對切換比例設置告警。
Q7：429 處理方案有哪些已知侷限？
退避會增加請求延遲，不適合對實時性要求極高的場景；跨廠商切換可能帶來輸出風格和格式差異，需要提前做迴歸測試；部分廠商只在控制檯展示限額，響應頭信息不完整，排查時只能依賴錯誤措辭和監控數據。
429 限流處理核心要點 Key Takeaways
- 429 只說明被限制：它不說明是誰限制、限制了什麼，不能直接等同於模型故障。
- 先讀錯誤原話：錯誤體措辭是判斷上游、網關或免費檔的最快線索。
- 再看響應頭：廠商前綴的
ratelimit字段與Retry-After是第二條證據鏈。 - 按維度對症處理：RPM 勻速、TPM 縮上下文、併發控 worker、配額耗盡直接切換。
- 先退避後切換：指數退避加全抖動，
Retry-After優先，重試有上限。 - 切換鏈分層設計：同模型換渠道優先，跨廠商換模型兜底，配合熔斷器。
- 用統一接口降成本：通過 API易 兼容 OpenAI 與 Anthropic 格式的接口，可用一套代碼管理主備模型。
總結
遇到 429 時，正確順序是“定位來源 → 判斷維度 → 退避 → 切換”，而不是一上來就換模型：
- 定位來源：錯誤體措辭加響應頭，分清上游廠商、網關和免費檔。
- 判斷維度：弄清是請求數、token 數、併發還是總配額，決定退避是否有效。
- 配置容錯：指數退避加抖動作爲第一道防線，分層故障切換加熔斷作爲第二道防線。
把這套流程固化到日誌、錯誤分類和客戶端配置中，429 就從“半夜報警”變成了可預期、可自愈的常規事件。
推薦通過 API易 apiyi.com 快速驗證主備模型的切換效果，接入說明見 docs.apiyi.com，涉及的模型價格與計費口徑請以 docs.apiyi.com/models 爲準。
📚 參考資料
- Rate Limit Reached in Claude Code: What Each 429 Message Means：Claude Code 中 429 錯誤信息的含義解讀
- 鏈接：
ofox.ai/blog -
說明： 說明如何通過服務端原話區分 Anthropic、網關與免費檔限流
-
Claude Code fallbackModel: 3-Tier Failover Setup：Claude Code 備用模型配置
- 鏈接：
ofox.ai/blog -
說明： 指出 fallbackModel 在 529 過載時觸發、最多 3 個模型，而非 429
-
LLM API Rate Limits Compared：5 家大模型廠商限流規則對比
- 鏈接：
ofox.ai/blog -
說明： 對比按 token、按併發與僅控制檯展示等不同限流口徑
-
API易 文檔中心與價格頁：接入說明與模型計費
- 鏈接：
docs.apiyi.com與docs.apiyi.com/models - 說明： 接口格式、base_url 配置與各模型實際價格以此爲準
作者：APIYI 技術團隊
技術交流：歡迎在 API易 apiyi.com 首頁聯繫我們交流限流與容錯實踐，更多接入資料可訪問 docs.apiyi.com 文檔中心
