简体中文繁體中文English
登入 免費開始
Troubleshooting · 排查手冊

Claude Code 報錯排查手冊

按錯誤碼對號入座，每條都給一句話原因和一步操作。大部分接入問題出在環境變數沒生效、地址寫錯、併發到頂這三件事上——先看速查表，多半三十秒就能解決。

速查表

你看到的多半是先做這一步
401 · Invalid tokenKey 沒生效或複製不全完整排查 →
403Key 被禁用或許可權不足完整排查 →
429 · rate limit併發到頂，不是沒錢完整排查 →
Connection error地址寫錯或網路不通完整排查 →
SSL / certificate代理或防火牆在中間拆包完整排查 →
model not found模型名帶錯版本或字尾完整排查 →
context length exceeded會話攢太長完整排查 →
流式回答中途斷網路或代理超時掐斷看代理超時設定
529 · overloaded 過載上游模型過載，非你的配置問題稍後重試或換模型
x-bb-api-key 等第三方報錯由其他服務返回，不是 9Coding 的報錯判斷報錯來源 →

連線與鑑權

401 · Invalid token#

症狀
請求直接被拒，響應體形如 {"error":{"code":"","message":"Invalid token (request id: 2026...)","type":"new_api_error"}}。
原因
服務端沒認出這把 Key。九成不是 Key 本身的問題，而是環境變數沒生效或複製時被截斷。
解決

先確認變數真的被讀到了：

terminal
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

輸出為空 → 變數沒寫進當前 shell 的配置檔案，或者寫完沒重開終端。Claude Code 只在啟動時讀一次環境變數，改完必須重開終端（或 source ~/.zshrc）。

有輸出但仍報 401 → 檢查 Key 是否以 sk-9c- 開頭、尾部有沒有漏字元。從控制台重新複製一次最穩妥。

403 · Forbidden#

症狀
Key 被識別了，但這次呼叫不被允許。
原因
Key 已被禁用、已刪除，或該 Key 被限制了可用範圍。
解決
到控制台的 Key 管理頁確認這把 Key 還在、狀態正常。刪掉重建一把是最快的驗證方式——新 Key 立刻生效，不需要等。

Connection error · 連不上#

症狀
請求還沒到服務端就失敗，報連線錯誤、ECONNREFUSED 或超時。
原因
要麼地址寫錯，要麼網路出不去。先把 Claude Code 排除在外，用 curl 直接打端點，一步就能分開這兩種情況。
解決
terminal
curl -s https://api.9coding.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

curl 能通（返回模型列表或 JSON 錯誤）→ 網路沒問題，是客戶端配置。檢查 ANTHROPIC_BASE_URL 有沒有拼錯、結尾多了 / 或多寫了 /v1。正確值就是 https://api.9coding.com，路徑由客戶端自己拼。

curl 也不通 → 網路或代理問題。檢查系統代理是否只對瀏覽器生效、公司網路有沒有攔截，終端裡試試 curl -v 看卡在哪一步。

SSL / certificate 錯誤#

症狀
報證書校驗失敗、unable to get local issuer certificate、握手超時。
原因
中間有代理或安全軟體在拆 TLS，而它的根證書沒被系統信任。
解決
把代理軟體的根證書裝進系統鑰匙串，或臨時關掉代理驗證是不是它。不要用跳過證書校驗的方式繞過——那等於把流量明文暴露給中間人。

限流與超時

429 · rate limit#

症狀
請求被限流，提示 rate limit 或 too many requests。
原因
這是併發到頂，不是餘額不夠。兩者的提示完全不同，餘額問題會明確說餘額不足。
解決

等幾秒重試，通常自行恢復。頻繁觸發說明並行開得太猛：把同時跑的任務數降下來。

批次指令碼一定要加指數退避——失敗後等 1 秒、2 秒、4 秒逐次拉長，而不是原地猛重試。密集重試只會讓限流持續更久。

529 · overloaded 模型過載#

症狀
返回 529、提示 overloaded 或模型過載。搜「claude 529 怎麼解決」的多半就是這個。
原因
上游模型本身在高負載，跟你的配置無關。熱門模型在高峰時段偶發。
解決
稍等重試；趕時間就先換一個同級模型繼續幹活。在 Claude Code 裡用 /model 切換，會話不會丟。
深入
如果它是斷在回答中間、一次都沒重試，那是另一條到達路徑，標準重試機制管不到它 —— 見 529 overloaded 詳解。

流式回答中途斷掉#

症狀
回答輸出到一半停住，沒有報錯，或提示連線被重置。
原因
流式響應是一條長連線，中間任何一環的空閒超時都會掐斷它——常見於公司代理和部分 VPN。
解決
把代理的讀超時調大（長回答很容易超過 60 秒），或臨時繞過代理驗證。判斷方法：同樣的問題讓它輸出短一點，如果短回答正常、長回答必斷，基本可以確定是超時掐斷。

模型與引數

model not found · 模型名不對#

症狀
提示模型不存在或不可用。
原因
手寫模型名帶錯了版本號或多餘字尾。模型 id 對大小寫和短橫線敏感，差一個字元就找不到。
解決

直接問服務端當前有哪些，照抄返回裡的 id：

terminal
curl -s https://api.9coding.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

在 Claude Code 裡用 /model 命令切換，從列表裡選，比手輸可靠。

context length exceeded · 上下文超限#

症狀
提示上下文超出限制、token 數超標。
原因
會話累積的內容超過了模型的上下文視窗。長會話或一次性讀入大檔案時最常見。
解決

/clear 開新會話，或 /compact 壓縮歷史後繼續。

長期辦法是別把整個倉庫一次性塞進去：讓它按需讀檔案，比預先灌滿上下文更省也更準。

以上都不是？按這個順序查

遇到沒見過的錯誤，不要從猜開始。這個順序能在幾分鐘內把範圍縮到一處：

  1. 看環境變數：echo $ANTHROPIC_BASE_URL $ANTHROPIC_AUTH_TOKEN。空的就是沒生效，重開終端。
  2. 繞過客戶端：用上面的 curl 直接打端點。能通就說明是客戶端配置，不通就是網路。
  3. 換個模型：單個模型出問題和整條通道出問題，處理方式完全不同。
  4. 最小復現：新開一個空會話、問一句最簡單的話。複雜會話裡的報錯往往和上下文有關，而不是接入本身。
  5. 還是不行就提交給我們——帶上下面這些資訊。
提交問題時請帶上這四樣：① 完整錯誤文字，尤其是裡面的 request id（形如 request id: 2026...，能直接定位到那一次呼叫）；② 發生時間；③ 用的模型名；④ 上面第 2 步 curl 的結果。有這四樣通常一次就能定位，只說「調不通」誰也查不了。

相關

免費開始 看接入教程