Claude API 错误码 400/401/403/429/500 排查指南

“claude code api error 400”、“claude code api error 403”、“claude api 错误码”、“claude api 401”、“claude api 429”、“claude api 500”、“claude api 排查”——这些搜索词背后的真实场景往往是：刚部署上线就 500、用了几天 Claude Code 突然 403、批量任务跑着跑着 429、模型名一个字母拼错就 400。本文按 HTTP 状态码顺序，把每一类错误的成因、典型场景、排查命令、修复策略全部讲清楚。

注意：Anthropic API 的错误结构与具体 error type 命名可能随版本调整，本文按当前主流 SDK 行为整理，请以 Anthropic 官方文档为准。

错误码总览

Anthropic API 在出错时返回 HTTP 状态码 + 一个标准 JSON 错误体：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: field required"
  }
}

排查的两条主线是 HTTP 状态码 + error.type。下表是常见错误的全景：

HTTP	error.type	含义	典型原因	重试
400	invalid_request_error	请求结构错	字段缺失 / 模型名错 / 超长	不重试
401	authentication_error	鉴权失败	key 错 / 缺 / 已撤销	不重试
403	permission_error	无权限	账号风控 / 区域受限 / 模型未开通	不重试
404	not_found_error	资源不存在	端点 / 模型 ID 错	不重试
413	request_too_large	请求体过大	超过单次最大 size	拆分后重试
429	rate_limit_error	速率限制	RPM/TPM/并发触顶	退避重试
500	api_error	服务端错误	Anthropic 后端故障	退避重试
503	overloaded_error	服务过载（部分版本）	高峰期容量不足	退避重试
529	overloaded_error	严重过载	模型层临时不可用	退避重试

接下来逐项展开。

400 invalid_request_error

400 是”你发的请求服务器读不懂”，最常出现在新手上手和模型版本切换两个场景。

典型错误体：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: at least one message is required"
  }
}

高频根因：

模型 ID 拼错或过期：claude-sonnet-4-6 写成 claude-sonet-4.6，claude-opus-4-7 写成 claude-opus-4.7（注意是 - 不是 .）。模型 ID 不能猜，去 Claude API 完整使用指南或官方 docs 抄。
max_tokens 缺失或为 0：Anthropic API 强制要 max_tokens，没有就直接 400。
messages 数组为空：批量代码里循环条件没 ready 就发请求。
消息顺序违规：第一条必须是 user，且 user 和 assistant 必须交替，不能连续两条 user。
system 字段位置错：system 应放在顶层，不应放进 messages 数组里（除非用最新支持的 system role 写法）。
超过上下文长度：单次请求总 token 超过模型支持的 context window，会被拒。
Tool / Schema 错：tool_use 的 JSON schema 不合法，或返回 tool_result 顺序错。
stop_sequences 太多 / 重复：stop 序列超过 4 个或重复。

排查步骤：

# 1. 把请求体打印出来
curl -v https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 64,
    "messages": [{"role":"user","content":"ping"}]
  }'

如果最小请求能通，再逐步加字段定位是哪行参数挂的。

Claude Code API Error 400 专项：

Claude Code 报 400 通常来自这几个地方：

启用了某个旧 / 内部 beta header，最新版本已不识别
ANTHROPIC_MODEL 环境变量设到了已 deprecate 的版本
自定义中转后端协议字段稍有差异
工具调用中的 input schema 不合规

定位办法：开 Claude Code 的 verbose log（claude --debug 或设 DEBUG=1），找到完整 request body，对照官方 API reference 比对。

401 authentication_error

401 = “你没鉴权，或鉴权信息无效”。

典型错误体：

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

高频根因：

x-api-key header 漏写：自己拼接 HTTP 时忘了带。
key 拼错：复制粘贴时漏字符 / 多空格 / 多了引号。SDK 里写 api_key="sk-ant-... " 末尾带空格也会挂。
key 已被 Revoke：控制台撤销过这把 key。
环境变量没生效：ANTHROPIC_API_KEY 在某些 shell 里没 export，或 systemd / Docker 容器里没传进去。
走中转用错了 base_url：中转要求的 header 字段名可能不同（如 Authorization: Bearer ...），照官方协议发会 401。

排查命令：

# Linux / macOS
echo "Key length: ${#ANTHROPIC_API_KEY}"
echo "Key prefix: ${ANTHROPIC_API_KEY:0:10}"

# Windows PowerShell
$env:ANTHROPIC_API_KEY.Length
$env:ANTHROPIC_API_KEY.Substring(0, 10)

一个合法的 Anthropic key 通常以 sk-ant- 开头、长度上百字符。如果对不上，多半是变量里塞了别的东西。

修复策略：

进 console.anthropic.com → API Keys → 看 key 是否 Active
如果用 .env 文件，确认进程已 reload 环境
如果跑在 Docker / Kubernetes，看 secret 是否真的注入到容器
如果走中转，确认 base_url + 鉴权方式与中转商文档一致

申请新 key 的完整流程见 Claude API Key 申请教程。

403 permission_error

403 = “我认识你的 key，但你没权限做这个操作”。它不是 key 写错了，而是 key 对应的账号 / IP / 资源被拦。

典型错误体：

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Your account is not authorized to access this model"
  }
}

高频根因：

账号风控：长期共享 key / 国内 IP / 异常用量曲线触发 abuse detection，账号被冻结或限制。
IP 地区限制：从受限国家 / 地区直接调官方 API，被边缘节点直接拦。
模型未开通：新发布的模型对部分账号默认未授权，需在控制台单独申请或等灰度。
Workspace 权限：key 只属于某个 Workspace，但调用的模型 / 功能在那个 Workspace 没启用。
Beta 功能未开通：用 anthropic-beta header 启用未邀请的特性。
企业策略：账号是组织的成员，被管理员限制了模型 / endpoint。

排查步骤：

# 用最小请求 + 最便宜模型测，剔除其它干扰
curl -v https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

如果 Haiku 也 403，几乎可以确定是账号 / IP 级问题。如果只有 Opus 4.7 等高端模型 403，是模型授权问题。

Claude Code API Error 403 专项：

Claude Code 报 403 最常见的就是：

用了中转 / 共享账号，账号被批量风控
VPN 节点被 Anthropic 标记
短时间内同一 key 在多个国家发请求（被识别为异常）
切换了 base_url 但忘了切配套 key

修复优先级：换干净 IP → 直连测试 → 联系账号支持。

404 not_found_error

404 = “你请求的端点 / 资源不存在”。

高频根因：

URL 拼错：/v1/messages 写成 /v1/message、/v1/chat/completions（那是 OpenAI 路径）。
走错协议：把 OpenAI 兼容协议发给 Anthropic 原生 endpoint。
模型 ID 错：部分 SDK 在 model 找不到时返回 404 而不是 400。
中转 base_url 路径前缀差异：有些中转要 /anthropic 前缀。

修复就是对照官方 endpoint：

POST https://api.anthropic.com/v1/messages
POST https://api.anthropic.com/v1/messages/count_tokens
POST https://api.anthropic.com/v1/messages/batches

413 request_too_large

413 = “请求体超过单次允许的最大 size”，注意它和上下文长度不完全一样，是 HTTP body 字节数维度。

修复策略：

拆分大批量请求
用 Messages Batches API 做离线大量请求
压缩 Vision 图片（不必传原图分辨率）
上下文做检索摘要 / 滑窗，不要把整个仓库塞进去

429 rate_limit_error

429 是生产环境最高频的可恢复错误，必须有重试策略。

典型响应头：

HTTP/1.1 429 Too Many Requests
retry-after: 5
anthropic-ratelimit-requests-limit: 50
anthropic-ratelimit-requests-remaining: 0
anthropic-ratelimit-requests-reset: 2026-05-11T08:30:15Z
anthropic-ratelimit-tokens-limit: 40000
anthropic-ratelimit-tokens-remaining: 0
anthropic-ratelimit-tokens-reset: 2026-05-11T08:30:30Z

触发维度：

限制	含义
RPM	每分钟请求数
TPM (input)	每分钟输入 token
TPM (output)	每分钟输出 token
并发	同一时刻进行中的请求数
日 / 周 / 月预算	Budget Alert 的硬上限

不同账号档位（Build / Scale / 大客户）的限额不同，可以在 console 的 Limits 页面看。

排查：

import time
from anthropic import RateLimitError

def call_with_retry(client, params, max_attempts=5):
    delay = 1.0
    for attempt in range(max_attempts):
        try:
            return client.messages.create(**params)
        except RateLimitError as e:
            retry_after = float(e.response.headers.get("retry-after", delay))
            time.sleep(retry_after + random.uniform(0, 0.5))
            delay = min(delay * 2, 30)
    raise RuntimeError("rate limit, gave up")

根治办法：

客户端限速：用 token bucket 把 RPS 控在限额 80% 内
切到 Batch API 走离线吞吐
联系销售提升 tier（Scale → 自定义 SLA）
把高频小请求合并、用 Prompt Caching 减少输入 token

如果是 Claude Code / Cursor 触发 429，通常和并发或 TPM 有关，把多 agent 并行数降下来即可。

500 / 503 / 529 服务端错误

这一组都属于 Anthropic 后端”暂时性”问题，5xx 都应该自动重试。

状态	典型场景
500 api_error	服务内部异常，偶发
503 service_unavailable	节点 / 路由暂时不可用
529 overloaded_error	模型层过载（高峰期常见，Opus 尤甚）

重试策略：

import time
import random
from anthropic import APIStatusError, APIConnectionError, RateLimitError

RETRYABLE_STATUS = {429, 500, 502, 503, 504, 529}

def safe_call(client, params, max_attempts=6):
    for attempt in range(max_attempts):
        try:
            return client.messages.create(**params)
        except RateLimitError:
            delay = 2 ** attempt + random.uniform(0, 1)
        except APIConnectionError:
            delay = 2 ** attempt + random.uniform(0, 1)
        except APIStatusError as e:
            if e.status_code not in RETRYABLE_STATUS:
                raise
            delay = 2 ** attempt + random.uniform(0, 1)
        time.sleep(min(delay, 60))
    raise RuntimeError("max retries exceeded")

关键参数：

指数退避：1s, 2s, 4s, 8s, 16s …
jitter：每次加 0-1s 随机，避免雪崩同步
上限：单次最多等 30-60 秒
总尝试次数：5-6 次足够，再多说明真出问题

怎么判断 Anthropic 在出故障：

status.anthropic.com 看是否有公告
自己加监控：5xx 比例突增 → 切流量到 Bedrock / Vertex 备份后端
关注 X / Twitter 上的 @AnthropicAI 公告

用 Claude Code / Cursor 报错时怎么定位

工具层报错时，第一步永远是拿到 底层 HTTP 状态码 + error.type，不要被 IDE 的二次包装迷惑。

Claude Code：

# 开 debug 日志
claude --debug

# 看实际 endpoint
echo $ANTHROPIC_BASE_URL

# 临时切回官方
unset ANTHROPIC_BASE_URL
claude

更详细的 Claude Code 排查思路见 Claude Code 是什么？开发者编码 AI 工具完整介绍。

Cursor / Continue：

设置里看 API 模式：Pro 订阅模式 vs 自带 key
Developer Tools → Network 看实际请求
如果错误码 → 对照本文章

通用判断流程：

状态码 = ?
error.type = ?
同账号同 key 用 curl 跑一次最小请求，看是否复现
切到 Haiku 测，剔除模型权限问题
切官方 base_url 测，剔除中转问题
切干净 IP 测，剔除地区 / 风控问题
还不行就提工单

排查 Checklist 速查

下面这张表打印出来贴墙上：

状态	第一步
400	把 request body 打印出来比对官方示例
401	重新检查 key 是否生效 / 拼写 / Revoke
403	切 Haiku + 干净 IP + 官方 base_url 复测
404	比对 endpoint URL 和模型 ID
413	拆请求或切 Batch API
429	看 retry-after header，指数退避
500/503/529	自动重试 + 看 status 页
连不上 / TLS 错	网络 / 防火墙 / 中间人问题

FAQ

Q：429 一直出现，是不是要充值？ 不一定。先看是 RPM 还是 TPM 触顶。RPM 是请求频率，加退避就能缓解；TPM 是 token 吞吐，要么减并发要么升 tier。

Q：500 报错要不要立刻报支持？ 偶发 1-2 次别紧张，正常重试就好。如果 5xx 比例持续 > 5% 或大面积报错，先看 status.anthropic.com，再开 ticket。

Q：claude code api error 400 怎么快速复现？ 拿到 Claude Code 的 verbose log → 找到 request body → 用 curl 重发 → 看是否依然 400。是的话比对 body；不是的话是 Claude Code 自己的状态污染。

Q：claude code api error 403 用 VPN 就能解吗？ 看根因。如果是 IP 风控，换干净节点能修；如果是账号本身被封，再换 VPN 也 403。

Q：要不要每个错误都重试？ 绝对不要。401 / 403 / 404 / 400 是确定性错误，重试只会浪费时间。只重试 408 / 429 / 5xx 和网络层错误。

Q：怎么避免误重试 user 已经看到的请求？ 用幂等 ID：自己生成一个 request_id 缓存请求，重试时复用，配合本地 dedupe 避免重复出账单。

Q：本地报错和生产报错不一样怎么办？ 99% 是环境变量 / 网络 / 账号差异。把生产能复现的最小 curl 拷到本地一次性跑，定位差异点。

错误码本身只是表象，真正高效的排查方法是建立”状态码 + error.type + headers + 最小复现”的肌肉记忆。把本文 Checklist 收藏，下次报错先按表走一遍，多数问题十分钟内可以定位到根因。