Claude Code「API Error: bad_response_status_code」— 解讀其底層狀態

這個錯誤只告訴您呼叫失敗，幾乎沒有說明原因。有用的資訊——狀態碼與供應商訊息——只差一個除錯旗標即可取得，而每個狀態都指向不同的修正方式。

錯誤

terminal

API Error: bad_response_status_code

(no status, no provider message — the wrapper hides both)

原因與解決方法一覽

原因	解決方法
底層為 401／403	針對自訂 base URL 的認證或標頭不符。請檢查設定了哪個認證變數。
底層為 404	可能是該主機不認識模型 ID，也可能是 base URL 多了一段路徑。
底層為 402	閘道錢包為空。請儲值；用戶端設定沒有問題。
底層為 429／529	受到速率限制或上游過載。請採用退避重試，而不是重新設定。
200 但回應內容不是 JSON	可能是強制入口網站、企業 Proxy 或錯誤頁面。狀態可能正常，但回應內容仍不可用。

將包裝錯誤轉為真正的錯誤

Claude Code 的除錯輸出會列印請求與上游回應。開啟除錯功能執行一次失敗呼叫，並讀取狀態列——此後的所有步驟都取決於該狀態列顯示的內容。

debug.sh

claude --debug 2>&1 | tee claude-debug.log

grep -iE 'status|http/|error' claude-debug.log | head -20

使用 curl 重現相同呼叫

從工具中取出 base URL 與認證資訊，直接發出請求。這一步就能區分「主機拒絕我們」與「用戶端格式錯誤」，而原始回應內容通常會以包裝錯誤捨棄的直白語言說明問題。

reproduce.sh

curl -i "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

確認 base URL 沒有尾端路徑

Claude Code 會附加自己的 `/v1/...` 路徑。若 base URL 已以 `/v1` 結尾，就會產生 `/v1/v1/messages`，任何主機都會以 404 回應——再次被包裝為 bad_response_status_code。請只設定來源網域。

base-url.sh

# Wrong — doubles the version segment
export ANTHROPIC_BASE_URL="https://api.kunavo.com/v1"

# Right — origin only
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

如果你透過 Kunavo 呼叫

對 Kunavo 而言，應立即辨識的兩個狀態是 402 與 401：402 表示錢包無法支付請求——問題在餘額，而非設定——401 表示 Kunavo 未收到可用的 sk-kn- 金鑰。它會從 Authorization: Bearer 或 x-api-key 讀取金鑰，因此請檢查 Claude Code 實際傳送的內容：放在 ANTHROPIC_API_KEY 中的金鑰需要在互動工作階段中進行一次性核准，拒絕後便會被忽略；而 ANTHROPIC_AUTH_TOKEN 會立即使用。兩種狀態都會以 JSON 內容說明原因，因此除錯日誌能提供確切答案，而不是僅供推測。失敗的請求不會計費。應設定哪個變數，以及原因，請參閱認證變數指南.

常見問題

這個錯誤可能是 Claude Code 自身的錯誤嗎？

很少。它是傳輸層的包裝錯誤：有某個項目回覆了，而回覆不是成功結果。使用 curl 重現即可確認——如果 curl 也失敗，問題就不在用戶端。

官方 API 可以運作，但我的閘道不行。

那麼差異在認證資訊或 base URL，而不是工具。請檢查閘道要求的認證標頭，以及 base URL 是否已包含 /v1。

我應該自動重試嗎？

只有在確認狀態後才重試。重試 401 或 404 沒有意義；對 429 或 529 採用退避重試才是正確做法。