Claude Code API 疑難排解
解決 Claude Code 速率限制、500、529 過載與 API 金鑰疑問
涵蓋 API 金鑰設定、Pro 或 Max 與 API 計費差異、Messages 相容端點、速率限制、伺服器錯誤和路由過載的排解指南。
claude-code-diagnostics
$ claude-code run --model claude-sonnetAPI Error: rate limit reachedstatus=429 route=messages tokens=128k retries=3下一步：降低並行量、核對金鑰、退避重試
4 類錯誤1 份排解流程3 項路由檢查
社群問題
排查錯誤時應該問什麼
社群討論可協助確定排查方向；實際限制、帳號狀態與錯誤含義，請以官方文件和請求紀錄核驗。
開發過程中觸發速率限制
限制來自帳號、工作區、模型路由，還是閘道？
先檢查帳號限制，再降低並行量，並使用較小的上下文重試。API 金鑰與 Pro 或 Max 訂閱
目前的驗證方式使用訂閱權限，還是 API 計費？
除非供應商明確關聯，否則應分別核對訂閱權限與 API 計費。代理迴圈中出現 500 或 529
是供應商過載、閘道路由故障，還是不斷重複的重試迴圈？
修改程式碼前，記錄狀態碼、請求 ID、路由、模型、權杖數與重試次數。錯誤分類
從狀態碼開始排查
先區分金鑰或權限問題、額度限制、伺服器錯誤與過載，再選擇處理方法。
429
觸發速率限制
帳號、工作區、模型或路由超過了請求數或權杖數限制。
- 減少並行代理任務
- 縮短過長上下文
- 採用退避重試
- 檢查額度與模型限制
500
API 伺服器錯誤
供應商或路由回傳伺服器端錯誤；重複失敗時需要核對路由證據。
- 記錄請求 ID
- 退避後重試一次
- 持續失敗時比較其他路由
- 不要先重寫提示詞
529
服務過載
上游服務負載過高。更換 API 金鑰通常無法解決過載。
- 等待並退避
- 嘗試備用模型
- 縮小請求規模
- 查看狀態頁與支援管道
401/403
API 金鑰或權限問題
目前金鑰可能不正確，或沒有對應模型、端點的存取權限。
- 核對 ANTHROPIC_API_KEY
- 檢查基底 URL
- 確認模型存取權限
- 核對實際計費來源
排解流程
修改程式碼前先收集事實
- 記錄完整錯誤、HTTP 狀態碼、模型、端點與時間。
- 確認使用 Anthropic 直連金鑰，還是相容閘道。
- 將 API 計費與額度和 Pro 或 Max 訂閱狀態分開檢查。
- 遇到 429，先降低並行量與上下文大小。
- 遇到 500 或 529，退避後重試一次，再比較其他路由或備用模型。
- 使用閘道時，核對 Messages 端點、模型路由、快取行為與支援說明。
Pro 或 Max 權限不等於 API 計費
核對目前金鑰、基底 URL 與計費來源。不要假定訂閱權限與 API 額度共用餘額。
取得 API 存取權使用閘道？請檢查 Messages 端點
Claude 相容用戶端需要正確的 Messages 端點、有效金鑰，以及能支援實際任務的模型路由。
查看文件常見問題
Claude Code API 錯誤
為什麼 Claude Code 顯示觸發速率限制？
請求數、權杖數或模型路由達到限制。請核對目前金鑰、工作區、路由、上下文大小與並行代理任務。
Pro 或 Max 包含 API 金鑰嗎？
除非官方帳號頁面另有說明，否則應分別核對訂閱權限與 API 計費，並確認目前驗證方式與計費來源。
出現 API Error 500 怎麼辦？
記錄請求 ID，退避後重試一次。持續失敗時比較其他路由，或將時間、模型與請求 ID 提供給支援人員。
529 overloaded 是什麼意思？
上游服務過載。可以等待、退避、縮小請求規模或使用備用路由。僅更換 API 金鑰通常無法解決過載本身。
參考來源
在哪裡核驗目前規則
限制與錯誤含義以官方文件為準。社群討論是排查線索，不能取代已驗證的事實。