← 博客
Claude APIErrorsTroubleshooting

Claude API 错误码大全：400、401、429、529 及解决方法

（文中价格随实时价格表更新）

简短回答

Claude API 的每个错误都以 JSON 返回，包含 HTTP 状态码和 error.type：400 invalid_request_error（请求体有问题）、401 authentication_error（缺少密钥或密钥错误）、403 permission_error、404 not_found_error（路径或模型 ID 错误）、413 request_too_large、429 rate_limit_error、500 api_error 和 529 overloaded_error。4xx 错误要通过修改请求来解决，原样重发只会再次失败；429、500、503 和 529 则应使用指数退避重试，并在响应带有 retry-after 头时遵守它。APIVAI 使用相同的错误码，另外在密钥预算用完时返回 402 insufficient_quota，默认限制为每个密钥每分钟 60 次请求。大多数 404 来自 Base URL：Anthropic 格式用 https://api.apivai.com，OpenAI 格式用 https://api.apivai.com/v1。

Claude API 的错误响应长什么样？

按照官方 Claude API 错误文档，Anthropic API 以 JSON 返回错误，顶层的 error 对象始终包含 type 和 message。APIVAI 返回的格式相同：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Not found. Check the model name and the endpoint path."
  }
}

OpenAI 格式（POST /v1/chat/completions 和 /v1/responses）传统上使用 {"error": {"message": "...", "type": "...", "param": null, "code": "..."}}。在 APIVAI 上，这些端点的错误也使用上面的结构。OpenAI 的 SDK 和工具读取的是 error.message 和 error.type，这两个字段始终存在；对于 400、404 和 413 错误，如果能说明是哪个字段出错，响应体里还可能带有 code 和 param。

排查时先看 error.message。对于请求问题（400、404、413），它通常会直接指出出错的字段或模型。

Claude API 各个错误码是什么意思？

HTTPerror.type含义怎么处理是否重试
400invalid_request_error请求体或参数错误修正消息里指出的字段否
401authentication_error缺少密钥或密钥无效检查密钥和请求头否
402insufficient_quota密钥预算已用完（APIVAI）在控制台给该密钥追加预算否
403permission_error账户已停用或无权访问该资源联系客服否
404not_found_error路径、Base URL 或模型 ID 错误检查 /v1 和模型 ID否
413request_too_large请求体过大减少发送的数据否
429rate_limit_error每分钟请求过多，或密钥预算用完退避等待；查看消息内容是，需退避
500api_error服务器意外错误退避重试是
503 / 529overloaded_error暂时过载退避重试是

Anthropic 官方列表中还有 402 billing_error（Anthropic 账户的付款问题）、409 conflict_error 和 504 timeout_error。对于长时间生成，官方建议使用流式输出来避免超时。在 APIVAI 上，402 始终表示你正在使用的密钥预算已用完。

为什么会出现 401「invalid x-api-key」或「Invalid API key」？

401 authentication_error 表示请求已经到达 API，但密钥未被接受。完全没有传密钥时，APIVAI 返回「Missing API key.」；密钥不属于你的账户时，返回「Invalid API key.」。

按顺序检查：

  • 请求头。 Anthropic 格式通常发送 x-api-key: <key>，OpenAI 格式发送 Authorization: Bearer <key>。APIVAI 在两种格式下都接受这两种请求头，所以这里的 401 是密钥本身的问题，与用哪个请求头无关。
  • 密钥文本。 从控制台重新复制一次；少复制一个字符、带上空格或引号都很常见。
  • 实际发送的是另一个密钥。 旧的 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 环境变量可能会覆盖你在工具设置里填写的密钥。Claude Code 会读取哪些变量，见 Claude Code 配置指南。
  • 密钥已删除或重新生成。 重新生成的密钥会替换旧密钥，所有用到它的工具都要更新。

如果是 403 permission_error 并提示「This account is disabled. Contact support.」，说明密钥有效但账户已停用；换密钥没有用，请联系客服。

如何解决 429 rate_limit_error 和 402 insufficient_quota？

在 APIVAI 上，每个密钥有两个限制：

  • 请求频率。 默认每个密钥每分钟 60 次请求。大量并发调用的 Agent 可能会超过这个限制。降低并发、退避重试，或联系客服提高限额。
  • 预算。 每个密钥都有自己的预算，在创建密钥或追加预算时从账户余额中划入。预算用完后，请求会返回 402 insufficient_quota（「This key has no budget left. Add budget to the key in the dashboard.」），或者返回消息里写明密钥预算已用完的 429。

预算类错误重试也不会消失。打开控制台，给这个密钥追加预算。如果账户余额也是空的，先充值（$10 起）。账户余额有钱而某个密钥没有预算的情况是可能的：这个密钥的请求只看它自己的预算。当前每 token 价格见价格页面。

overloaded_error（529）是什么？应该怎么重试？

overloaded_error 表示服务暂时过载。它不是由你的请求引起的，同一个请求稍后通常就能成功。APIVAI 会以 529 返回它，或以类型同为 overloaded_error 的 503 返回。500 api_error 的处理方式相同。

正确做法是指数退避：先等约 1 秒，然后 2、4、8 秒，加上一点随机抖动（jitter），尝试几次后停止。如果响应带有 retry-after 头，至少等待这么久；只要有设置，APIVAI 就会把 retry-after 和 retry-after-ms 透传给你。

Anthropic 官方 SDK 已经内置了这一机制：默认对连接错误、429 和 5xx 响应重试两次，使用指数退避并遵守 retry-after。你只需调大 max_retries：

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.apivai.com",
    api_key="YOUR_APIVAI_KEY",
    max_retries=5,  # default is 2
)

try:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        messages=[{"role": "user", "content": "Hello"}],
    )
    print("".join(b.text for b in msg.content if b.type == "text"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.response.headers.get("request-id"), e.message)

不用 SDK 时，一个小循环就够了。它只重试临时性错误码，遇到与预算有关的 429 就停止：

import random, time, requests

RETRY = {429, 500, 503, 529}

def post_with_backoff(url, headers, body, attempts=5):
    for i in range(attempts):
        r = requests.post(url, headers=headers, json=body, timeout=600)
        if r.status_code not in RETRY or "budget" in r.text:
            return r
        wait = float(r.headers.get("retry-after", 2 ** i))
        time.sleep(wait + random.random())
    return r

为什么会出现 404 not_found_error？

几乎总是 Base URL 或模型 ID 的问题：

  • Anthropic 格式： Base URL 填 https://api.apivai.com，不带 /v1。Anthropic SDK 和 Claude Code 会自己加上 /v1/messages，所以填 https://api.apivai.com/v1 会变成 /v1/v1/messages 而失败。
  • OpenAI 格式： Base URL 填 https://api.apivai.com/v1，/v1 只出现一次。少了它，请求会发到 /chat/completions，APIVAI 返回「Unknown endpoint」。
  • 主机名错误： 请求发到 apivai.com 而不是 api.apivai.com 时，会收到 404，消息为「Wrong base URL」并列出两个正确地址。
  • 模型 ID： 使用精确的 ID，例如 claude-sonnet-4-6，而不是显示名称。列出你的密钥可用的 ID：
curl https://api.apivai.com/v1/models \
  -H "Authorization: Bearer YOUR_APIVAI_KEY"

Claude 模型两种格式都能用；GPT 模型（例如 gpt-5.5）只能用 OpenAI 格式。两种格式的详细说明见 Claude API 代理和 OpenAI 兼容 API。

为什么会出现 400 invalid_request_error？

400 表示 API 理解了请求，但拒绝了其中的内容。消息里会写明原因。常见情况：

  • Anthropic 格式的请求缺少 max_tokens（这是必填参数）。
  • 对话以 assistant 消息结尾（prefill）。Claude 4.6 及更新的模型会拒绝它，最后一条必须是 user 消息。
  • 使用了旧的 thinking 设置：较新的模型，例如 claude-opus-5-5，会拒绝 thinking: {"type": "enabled"}，要求改用 adaptive thinking。删除 thinking 字段即可使用默认设置。
  • 在工具调用循环中，thinking 块在回传前被修改或删掉。请按收到时的原样传回。

还有一个相关问题根本不报错：回复为空或被截断。 thinking 默认开启，其 token 计为输出 token，所以 max_tokens 太小可能在出现任何文本之前就被用完。此时响应以 stop_reason: "max_tokens" 结束（OpenAI 格式为 finish_reason: "length"）。把 max_tokens 提高到 4096 或以上。

413 request_too_large 表示请求体本身太大。Anthropic 对 Messages API 的限制是 32 MB。常见原因是大的 base64 文件和过长的历史记录：少发或发更小的文件，或者裁掉早期的对话轮次。

流式响应中的错误是怎样出现的？

使用 "stream": true 时，流一开始 HTTP 状态就是 200，之后的失败无法再改变它，错误会作为流中的一个事件到达。Anthropic 流式文档给出的示例如下：

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

如果经过 APIVAI 的流在完成前中断，APIVAI 会发送一个 event: error，类型为 api_error，消息为「The response was interrupted. Please retry.」，而不是悄无声息地结束，因此 SDK 会抛出异常，而不是返回半截回答。按 500 处理即可：重试整个请求。

如何找到 request ID？

响应可能带有 request-id 头（有些服务用 x-request-id）；只要存在，APIVAI 就会透传。用 curl 打印响应头：

curl -sS -D - https://api.apivai.com/v1/messages \
  -H "x-api-key: YOUR_APIVAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hi"}]}'

在 Python SDK 中，成功的响应有 msg._request_id，异常对象有 e.response.headers。联系客服时请附上 ID、时间和错误消息。

最常见的原因一览

现象可能原因解决方法
每个请求都是 404/v1 缺失、多余或重复Anthropic：https://api.apivai.com；OpenAI：https://api.apivai.com/v1
密钥看起来没错却 401旧的环境变量发送了另一个密钥删除它或换成 APIVAI 密钥
404 或 400 提到模型名拼写错误或用了显示名称从 GET /v1/models 复制 ID
回复为空或被截断开启 thinking 时 max_tokens 太小4096 或以上
413请求体中有大文件减少发送的数据
Agent 运行时出现 429每分钟超过 60 次请求降低并发，退避重试
402，或提到预算的 429密钥预算用完给密钥追加预算
529 / 503暂时过载退避重试

各工具的具体配置见文档，以及 Cline 配置 Claude 和 GPT 等教程。

常见问题

400 或 401 错误需要重试吗？

不需要。除 429 以外的 4xx 错误说明请求或密钥有问题，同样的请求会以同样的方式失败。先解决原因。

429 和 529 有什么区别？

429 与你自己的限制有关：每分钟请求数，在 APIVAI 上还包括密钥预算。529 overloaded_error 是与你的用量无关的暂时过载；频率导致的 429 和 529 都应退避重试。

Anthropic SDK 会自动重试吗？

会。默认对连接错误、429 和 5xx 响应重试两次，使用指数退避并遵守 retry-after。在客户端上设置 max_retries 即可修改，设为 0 则关闭重试。

为什么回复是空的却没有报错？

thinking 在输出可见文本之前就用完了全部 max_tokens。把 max_tokens 提高到 4096 或以上；thinking token 按输出 token 计费。

账户里有余额，为什么还会收到 402？

账户余额和密钥预算是分开的。每个密钥只消耗自己的预算；在控制台给这个密钥追加预算即可。

注册账户，充值 $10 起，创建一个密钥即可通过同一个 API 调用 Claude 和 GPT。

准备好了吗？

30 秒获取 API 密钥，按量付费使用 Claude 和 GPT

开始使用