Claude API 報錯 400 / 401 / 403 / 413 / 500 怎麼排查：錯誤類型、request_id 和常見 400 原因

本文根據 Claude 官方《Claude API errors》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。API 是按用量計費的獨立服務，與 Claude 訂閱分開計算，Key 的獲取見 /guides/claude-api-key-console。429 限流請看 /guides/claude-api-error-429-rate-limit，529 過載請看 /guides/claude-api-error-529-overloaded，本文不重複。

適用於誰

調用 Claude API 時收到 400、401、402、403、404、413、500、504 這類狀態碼的開發者。官方整理了一張狀態碼和錯誤類型的對照表，本文把它翻成中文，並補上最常見的幾類 400 報錯。

結論先說

1. 先看響應體裏的 error.type 和 message，再看狀態碼。 同一個狀態碼可能對應不同原因，資訊裏常直接寫了問題。
2. 4xx 一般是你這邊要改：參數、密鑰、權限、請求大小；5xx 一般可以稍後重試，重試仍失敗再帶着 request_id 聯絡官方。
3. 每個響應都有 request_id，出了問題先記下來，求助時附上。
4. 流式請求可能在返回 200 之後才出錯，要處理 error 事件。
5. 413 在第一方 API 上由 Cloudflare 攔截，請求都沒到 API 伺服器，要從請求體大小入手。

圖：本站根據 Claude 官方《Claude API errors》 整理的示意圖

一、官方的狀態碼對照

429（rate_limit_error）和 529（overloaded_error）見前面兩篇專文。

二、錯誤響應長什麼樣

錯誤總是 JSON，頂層 type 是 error，裏面的 error 對象帶 type 和 message，另有 request_id 字段。官方示例：

json
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

每個響應還有同樣內容的 request-id 響應頭。在 SDK 裏，Python 和 TypeScript 都能從返回對象的 _request_id 屬性讀到。官方提醒，這些對象裏的值以後可能增加新的 type，所以不要把錯誤類型寫成死的窮舉。

三、400 invalid_request_error：先查什麼

官方對 400 的定義很寬：請求格式或內容有問題，也可能表示其他沒單獨列出的 4XX。另外，如果你的組織或工作區觸達了你自己設定的花費上限，同樣返回 400（Claude Code 工作區的上限可能返回 429）。

官方在“常見校驗錯誤”裏列了幾類，覆蓋了現在最容易遇到的情況：

• 預填被拒：Claude 4.6 及之後的模型不支持預填助手消息，對話必須以用戶消息結尾。改用結構化輸出（見 /guides/claude-api-structured-outputs）、系統提示指令或 output_config.format；
• 思考塊被改動：最近一條助手消息裏的 thinking 或 redacted_thinking 塊被編輯、重排、過濾或重建，會返回 400。工具調用後要把這些塊原樣傳回，包括 thinking 字段為空的塊；
• 舊思考寫法被拒：Claude 4.7 及之後的模型不支持 thinking.type 為 enabled，應使用 adaptive 並配合 effort；反過來，較舊的 4.5 及更早模型不支持 adaptive。細節見 /guides/claude-api-extended-thinking；
• 無法關閉思考：部分模型的思考始終開啟，把 thinking 設為 disabled 會 400；
• 強制工具調用被拒：Opus 5.5、Sonnet 5.5、Fable 5.1、Mythos 5.1 不支持 tool_choice 取 any 或指定工具，用 auto 即可，必要時配合嚴格工具調用；
• 花費上限：檢查控制檯裏為組織或工作區設定的限額。

排查順序可以這樣走：先讀 message；再核對是否傳了該模型不支持的參數（採樣參數、預填、思考設定、tool_choice）；再核對消息結構（角色交替、內容塊類型）；最後核對圖片、PDF 的限制，見 /guides/claude-api-image-input 與 /guides/claude-api-pdf-support。

四、401 authentication_error：密鑰有問題

官方說明：API 密鑰格式錯誤、已被撤銷或已過期都會返回 401。檢查：

• 環境變量裏的 Key 有沒有多餘空格、引號或換行；
• Key 是否在控制檯裏被刪除或輪換（獲取與管理見 /guides/claude-api-key-console）；
• 請求頭是否帶對：SDK 會自動帶，手寫 HTTP 請求要帶 x-api-key 和 anthropic-version。

有一種 401 不是密鑰的問題：如果資訊以 “CORS requests are not allowed for this Organization” 開頭，說明請求帶了瀏覽器才會加的 Origin 頭，而你的組織不允許從瀏覽器直接調用 Claude API（官方舉例：啟用了零數據保留，或 Compliance API）。改請求頭沒用，應當由你自己的後端發請求。

五、402、403、404、409

• 402 billing_error：帳單或付款資訊有問題，去控制檯檢查付款資訊；
• 403 permission_error：密鑰無權使用該資源，檢查組織的訪問權限和工作區設定；
• 404 not_found_error：檢查接口路徑和 URL 裏的資源編號（比如文件 ID、批次 ID）；
• 409 conflict_error：請求與資源當前狀態衝突，例如資源被並發修改，或要求唯一的值已被佔用。先處理衝突，再重試。

六、413 request_too_large：請求太大

官方給出的第一方 Claude API 單個請求上限：

超過就返回 413，並且官方說明在第一方 API 上，這個錯誤是 Cloudflare 在請求到達 API 伺服器之前返回的。處理辦法：減小請求體。最常見的原因是大量 base64 圖片或 PDF，改用 Files API 上載後引用 file_id（見 /guides/claude-api-files-api），或拆分成多個請求。

圖：本站根據 Claude 官方《Claude API errors》 整理的示意圖

七、500 api_error 與 504 timeout_error

• 500 api_error：Anthropic 內部的意外錯誤。官方建議用指數退避重試，持續出現就聯絡官方並附上 request_id；
• 504 timeout_error：請求處理超時。官方特別說明，timeout_error 也會出現在別的狀態碼上，比如請求在伺服器時限內還沒開始響應時返回 500。長耗時的 Messages 請求請用流式，見 /guides/claude-api-streaming，或用批量接口。

官方對長請求的建議：不要在不用流式的情況下把 max_tokens 設得很大，因為有些網絡會掐斷空閒連接，導致請求失敗或超時卻沒收到響應；批量接口讓你輪詢結果，不必保持一條不間斷的網絡連接，見 /guides/claude-api-message-batches。

八、SDK 已經幫你做了什麼

官方 SDK 會自動重試暫時性錯誤（連接錯誤、限流、5xx），預設重試 2 次，帶指數退避，並遵守 retry-after 響應頭。可用 max_retries（TypeScript 裏是 maxRetries）調整。SDK 還把錯誤拋成有類型的異常，例如 404 對應 anthropic.NotFoundError。官方建議捕獲具體的異常類，而不是去匹配錯誤訊息的字符串，並且先處理最具體的類。TypeScript 裏的異常類對應關係見 /guides/claude-api-typescript-quickstart。

常見問題

Q：同一個請求有時 200 有時 5xx？

5xx 多是暫時性問題，SDK 預設會重試。持續出現時，記錄 request_id 聯絡官方。

Q：流式請求顯示成功，但內容中斷？

流在 200 之後仍可能出錯，檢查有沒有收到 error 事件。

Q：錯誤訊息是英文，我看不懂？

本文列出的是官方給出的片段，把完整的英文資訊原樣複製進搜尋或官方文檔，通常能定位到對應的頁面。

參考資料

• Claude 官方：Claude API errors — https://platform.claude.com/docs/en/api/errors