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