編碼過程中達到速率限制
帳號、工作區、模型或路由傳送的請求數或 Token 數超過限制。
降低並行 Agent 數 · 縮短上下文Claude Code API 疑難排解
解決 Claude Code 限流、500、529 過載和 API Key 混淆
一份涵蓋 API Key 設定、Pro 或 Max 與 API 計費、Messages 相容端點、限流、伺服器錯誤和路由過載的排查手冊。
claude-code-diagnostics
$ claude-code run --model claude-sonnetAPI 錯誤：達到速率限制status=429 route=messages tokens=128k retries=3下一步：降低並行、核對 Key、退避重試
4 類錯誤1 份手冊0 個薄內容頁
社群訊號
開發者在公開討論中反覆追問什麼
把 Reddit 和 X 上反覆出現的問題整理成穩定、可核實的排查提示。
API Key 與 Pro 或 Max 訂閱的差異
檢查實際使用的 Key、Base URL 和計費來源，不要假設訂閱方案與 API 額度共用同一餘額。
檢查模型權限 · 分開檢查訂閱登入和 API 計費Agent 循環中出現 500 或 529
供應商或路由傳回伺服器故障。一次重試可能恢復；持續失敗需要核對路由證據。 上游服務負載過高，通常更換 API Key 無法解決。
記錄 request id · 執行退避錯誤地圖
先看狀態碼，不要先聽傳聞
最快的方法是先分清 Key、額度、伺服器錯誤和過載問題。
429
達到速率限制
帳號、工作區、模型或路由傳送的請求數或 Token 數超過限制。
- 降低並行 Agent 數
- 縮短上下文
- 退避後重試
- 檢查目前額度和模型限制
500
API 伺服器錯誤
供應商或路由傳回伺服器故障。一次重試可能恢復；持續失敗需要核對路由證據。
- 記錄 request id
- 只重試一次
- 重複失敗時切換路由
- 不要先改寫提示詞
529
上游過載
上游服務負載過高，通常更換 API Key 無法解決。
- 執行退避
- 使用備援模型
- 減小請求內容
- 檢查支援或狀態頻道
401/403
API Key 或權限問題
Claude Code 沒有使用預期的 Key，或該 Key 無權存取要求的模型或端點。
- 確認 ANTHROPIC_API_KEY
- 檢查 Base URL
- 檢查模型權限
- 分開檢查訂閱登入和 API 計費
排查手冊
改程式碼前，先收集這些事實
- 記錄完整錯誤文字、HTTP 狀態碼、模型、端點和發生時間。
- 確認 Claude Code 使用 Anthropic 直連 Key，還是相容網關的 Base URL。
- 把 API Key 計費與額度和 Claude Pro 或 Max 訂閱狀態分開檢查。
- 遇到 429 時，先降低並行和上下文長度，再考慮切換供應商。
- 遇到 500 或 529 時，退避重試一次，再比較其他路由或備援模型。
- 使用網關時，先核對 Messages 相容端點、模型路由、快取行為和支援頁面。
Pro 或 Max 不等於 API 計費
檢查實際使用的 Key、Base URL 和計費來源，不要假設訂閱方案與 API 額度共用同一餘額。
取得 API 存取使用網關？先核對 Messages 端點
Claude Code 類客戶端通常需要 Messages 相容端點、有效的 API Key，以及支援目前工作負載的模型路由。
查看文件常見問題
Claude Code API 錯誤
為什麼 Claude Code 提示達到速率限制？
帳號、工作區、模型或路由傳送的請求數或 Token 數超過限制。 降低並行 Agent 數 · 縮短上下文 · 退避後重試 · 檢查目前額度和模型限制
Claude Pro 或 Max 包含 API Key 嗎？
檢查實際使用的 Key、Base URL 和計費來源，不要假設訂閱方案與 API 額度共用同一餘額。
遇到 API 500 錯誤該怎麼辦？
供應商或路由傳回伺服器故障。一次重試可能恢復；持續失敗需要核對路由證據。 記錄 request id · 只重試一次 · 重複失敗時切換路由 · 不要先改寫提示詞
529 過載是什麼意思？
上游服務負載過高，通常更換 API Key 無法解決。 執行退避 · 使用備援模型 · 減小請求內容 · 檢查支援或狀態頻道
資料來源
去哪裡核對目前規則
最終限額和錯誤含義以官方文件為準；社群討論只用於判斷需求，不作為事實來源。