Claude API Key 在哪获取？申请步骤详解

2601_96343664

620人浏览 · 2026-06-15 16:26:49

2601_96343664 · 2026-06-15 16:26:49 发布

Claude API 常见报错排查：401、429、超时到底怎么处理？

在调用 Claude API 的时候，很多问题其实并不是“模型出故障了”，而是卡在了认证、限流、网络，或者部署环境这些更基础的环节上。与其把所有错误码都罗列一遍，不如先把开发者最常遇到、也最容易搜的几个问题讲清楚：Claude API 401、Claude API 429，以及 timeout 超时。下面会直接围绕这些场景给出排查思路和处理办法。

说明：本文提到的“Claude API”，主要指 Anthropic 原生 API，以及一些兼容 Anthropic API 的接入方式。如果你用的是 Claude Code、AWS Bedrock、OpenRouter、TypingMind、ClaudeAPI 这类第三方工具或兼容平台，那么错误码有可能被平台重新包装过。具体的限制、计费、线路、模型支持情况，还是要以对应平台的最新说明为准。另外，ClaudeAPI 是第三方 Claude API 兼容接入服务平台，并不是 Anthropic 官方服务。

先说结论：401、429、超时分别该怎么处理？

报错现象	最可能的原因	先做什么	要不要重试
401 `authentication_error`	API Key 缺失、无效，OAuth 过期，或者代理把 header 丢了	先用 curl 发一个最小请求验证 Key	不建议
429 `rate_limit_error`	RPM、TPM、日限额、模型额度或平台配额超了	先看 `error.message`，判断到底是哪类限制	可以，但必须退避
请求超时 timeout	网络、代理、生成太慢、上下文太长、网关超时	先区分是连接超时、读取超时，还是总超时	看情况
529 `overloaded_error`	服务端临时过载	指数退避、稍后再试，必要时降级模型	可以

简单理解就是：

401 不要一上来就重试，这类问题大多是认证没配对，先修 Key、header 或登录态。
429 也不是简单加个 sleep 就完事，要先判断是请求数超了，还是 token 用得太猛。
timeout 不一定是 Claude API 返回的错误，它可能发生在 SDK、代理、Serverless、Nginx，甚至浏览器这一层。
429 和 529 不是一回事：429 通常跟你的账号、组织、模型或平台配额有关；529 更像是服务端一时扛不住了。

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

Claude API 报错时，通常会返回类似下面这样的结构：

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

排查时不要只截一张“报错了”的图，最好把下面这些信息都记下来：

HTTP status，比如 401、429、500、529；
error.type，比如 authentication_error、rate_limit_error；
error.message，这里往往会写清楚认证失败或限流的具体原因；
request-id / x-request-id；
使用的 model；
是否开启 stream；
输入长度、历史对话轮数、文件大小、预估 token；
max_tokens 设置；
retry 次数；
latency，也就是耗时；
provider：到底是 Anthropic 官方 API、Bedrock、Claude Code，还是第三方兼容平台。

如果你用的是 SSE 流式响应，还要额外注意一点：HTTP 200 只代表连接一开始成功了，不代表整个生成过程一定成功。流式输出过程中仍然可能中断，也可能在流里返回错误。因此代码里要捕获 stream 异常，保存已经生成的 partial output，并记录 request-id，后续排查会方便很多。

401 authentication_error：先查 API Key、OAuth 和环境变量

401 一般代表什么？

Claude API 返回 401，通常就是认证出了问题。常见原因有这些：

API Key 根本没传；
API Key 写错、失效、被删除，或者复制时带了空格和换行；
环境变量没有被当前进程读取到；
header 写错了；
代理、网关、Cloudflare Worker、Nginx 转发时把 x-api-key 丢掉了；
Claude Code 使用的 OAuth token 过期；
把 Claude Max / Claude Pro 订阅误以为是 API Key；
第三方工具里的 provider、base URL 或鉴权字段配错了。

第一步：先用 curl 验证 Key 是否真的可用

不要一开始就在业务代码里绕来绕去。最稳妥的做法，是先绕过你的项目代码，用一个最小请求测试 Key：

curl 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-3-5-sonnet-latest",
    "max_tokens": 32,
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

如果这个 curl 请求都返回 401，那就优先检查下面几件事：

$ANTHROPIC_API_KEY 是不是空的；
Key 是否是在 Console 里正确创建的；
复制 Key 时有没有多带空格、换行或引号；
当前账户或项目是否已经具备 API 使用条件；
有没有把 Claude Web 登录态、Claude Max 订阅当成 API Key 来用。

这里也提醒一下，不要用浏览器直接打开 API 地址来判断能不能用，更不要把完整 Key 打进日志或者发到论坛、群聊里。

第二步：检查代码里的认证写法

Anthropic 原生 API 常用的是 x-api-key，通常还需要带上 anthropic-version。不少从 OpenAI SDK 或 OpenAI 接口迁移过来的用户，会习惯性写成：

Authorization: Bearer sk-xxx

但在 Anthropic 原生 API 场景下，这通常不是正确写法。原生 HTTP header 一般类似这样：

x-api-key: your_api_key
anthropic-version: 2023-06-01
content-type: application/json

当然，如果你接入的是 OpenAI-compatible gateway，或者某个第三方兼容平台，那就不能照搬 Anthropic 官方 API 的 header 规则了。这个时候要看平台文档，它要求用什么 header、什么 base URL，就按它的来，千万不要混用。

第三步：别忽略 `.env`、Docker 和 CI/CD

很多时候，Claude API 401 并不是 Key 真失效了，而是程序根本没有读到这个 Key。常见坑包括：

.env 文件改了，但服务没有重启；
变量名写成了 CLAUDE_API_KEY，而 SDK 实际读取的是 ANTHROPIC_API_KEY；
Docker Compose 没有把 secret 注入容器；
GitHub Actions 里创建了 secret，但没有映射到 job 的 env；
本地 shell 有变量，生产环境的进程却没有；
Key 前后带了引号、空格或换行；
前端代码尝试直接调用 API，结果 Key 暴露，或者被浏览器环境限制。

排查时可以打印 Key 的长度，但不要打印完整 Key：

import os

key = os.getenv("ANTHROPIC_API_KEY")
print("key exists:", bool(key), "length:", len(key or ""))

这样既能确认变量有没有读到，也不会把敏感信息泄露出去。

Claude Code、Claude Max、第三方工具里的 401 有什么区别？

这里很容易混淆，建议把几个入口分清楚：

Anthropic API Key：一般在 Console 里创建，用于 API 调用；
Claude Web / Claude Max / Pro：这是网页端或订阅服务，不等同于 API Key，也不等同于 API 额度；
Claude Code：可能使用 OAuth 登录，也可能配置 API Key 或 Bedrock；
AWS Bedrock：走的是 AWS IAM、区域和 Bedrock 配额，不使用 Anthropic API Key；
第三方工具或兼容平台：往往有自己的鉴权字段、base URL、限流规则和错误包装。

所以，如果 Claude Code 报 401，先看是否需要重新登录，或者刷新 OAuth。要是 LibreChat、TypingMind 之类的工具报 401，就先检查 provider、base URL、Key 字段，以及容器里的环境变量是否真的生效。

429 rate_limit_error：并不只是“请求太快了”

429 常见原因有哪些？

Claude API 返回 429，意思是触发了限制。但这个限制不一定是“请求太频繁”，也可能是 token、预算、模型或平台层面的限制。常见情况包括：

RPM，也就是每分钟请求数超限；
input TPM，每分钟输入 token 超限；
output TPM，每分钟输出 token 超限；
单次请求的上下文太长；
历史消息、system prompt、工具定义、上传文件叠加后 token 过大；
日限额、预算或 usage tier 限制；
模型级别的限制；
组织级别的限制；
短时间流量突然上涨，触发 acceleration limit；
Bedrock、OpenRouter、ClaudeAPI 等平台自己的配额或限流。

这些限制会随着模型、组织、地区、usage tier 和服务商变化，不建议在代码里写死。实际排查时，要以控制台、官方文档、响应头，以及对应平台的说明为准。

怎么从错误信息判断是哪种 429？

优先看 error.message 里的关键词：

message 关键词	可能含义	优先怎么处理
`requests per minute`	RPM 超限	降并发、排队、令牌桶
`input tokens per minute`	输入 TPM 超限	减少上下文、拆分请求
`output tokens per minute`	输出 TPM 超限	降低 `max_tokens`
`daily limit`	日限额或预算限制	等额度恢复，或调整预算
`too many tokens`	单次请求或窗口 token 太大	压缩 prompt、拆分文档
只写 `rate limit`	泛化限流	结合日志、响应头和控制台一起看

要注意的是，一次请求里的 token 不只是你当前发的那句话。历史对话、system prompt、工具 schema、文件内容、检索结果，都会一起计入。

如果是请求数超限，该怎么限流？

如果 429 是请求数超限，千万不要“失败后立刻重试”。这很容易把系统打成重试风暴，越重试越失败。更稳的做法是：

降低 worker 并发；
引入任务队列；
按模型维度做限流；
使用令牌桶或漏桶；
多实例服务使用共享限流状态；
批量任务做削峰填谷；
避免每个请求各自无限重试。

换句话说，429 不是简单睡一秒就能解决的。你需要让请求进入一个可控的节奏里。

如果是 token 超限，该怎么减少 token？

如果是 token 相关的限制，就要从请求内容本身下手：

多轮对话只保留最近 N 轮；
对较早的上下文做摘要；
压缩 system prompt；
精简工具定义；
大文件先抽取关键段落，再送进模型；
长文档拆分处理；
降低 max_tokens；
给不同模型设置不同的 token 预算；
在日志里记录历史轮数、prompt 长度、文件大小和预估 token。

很多 429 看起来像“调用太频繁”，实际上是上下文太肥了。尤其是带文件、检索结果、工具调用的场景，更要注意 token 预算。

429 到底该怎么重试？

429 可以重试，但一定要有边界，不能无脑重试。比较合理的策略是：

优先尊重 retry-after；
如果没有 retry-after，就使用指数退避；
加入 jitter，避免所有请求同一时间恢复；
设置最大重试次数；
设置总超时预算；
高并发场景必须配合队列和限流；
401、403、400 这类错误通常不要重试。

可以按下面这个思路处理：

if status in [401, 403, 400]:
    fail fast
elif status == 429:
    wait retry-after or exponential_backoff_with_jitter
elif status in [500, 529] or timeout:
    retry with backoff
else:
    inspect error

timeout 超时：先分清连接超时、读取超时和流式中断

先判断是哪一种超时

类型	典型表现	常见原因	处理方向
DNS/连接超时	请求还没连上	网络、代理、DNS、防火墙	检查网络和 base URL
TLS/握手超时	HTTPS 建连失败	代理、证书、网络拦截	检查证书和代理配置
读取超时	请求发出去后长时间没响应	上下文大、生成慢	开 stream，调整 read timeout
总超时	达到客户端总耗时限制	`max_tokens` 大、任务重	拆任务，调整 total timeout
网关超时	504、函数超时	Nginx、Vercel、Lambda 限制	异步化或流式返回
流式中断	已经输出一部分后断开	网络抖动、SSE 被代理截断	保存 partial output，必要时重试

Claude 的长上下文、较大的 max_tokens、文件处理、工具调用，都可能让首 token 或完整响应变慢。如果你用的是非流式请求，就必须等完整结果回来，当然更容易被客户端、网关或 Serverless 平台截断。

更推荐的处理方式

遇到 timeout，可以从这些方向优化：

开启 streaming，降低用户等待感；
区分 connect timeout、read timeout 和 total timeout；
降低 max_tokens；
缩短历史上下文；
把大任务拆成多个小请求；
长任务放到后台队列，前端轮询结果；
对 timeout、500、529 做有限重试；
流式响应中断时保存已经生成的内容；
确认代理层支持 SSE；
不要在浏览器端直接暴露 API Key，最好由后端转发，并加上限流和鉴权。

说白了，超时问题不一定是模型慢，也可能是你的链路里某一层等不住了。

部署环境里还有一些额外坑

如果你的服务部署在 Vercel、Netlify、Cloudflare Worker、AWS Lambda、API Gateway、Nginx 后面，还要特别留意平台自己的超时限制。比如：

Serverless 函数通常不适合长时间阻塞；
Nginx 要关注 proxy_read_timeout；
Cloudflare、API Gateway 可能会中断长连接；
SSE 需要代理正确转发，不能被缓存或缓冲卡住；
跨境网络、移动网络可能带来偶发断流。

这类问题在本地测试可能完全正常，一上生产就暴露出来，所以最好提前压测和观察日志。

可直接参考的错误处理代码模板

Python 示例：退避、限流与 request-id 思路

import random
import time
import anthropic

client = anthropic.Anthropic()

def call_claude(messages, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model="claude-3-5-sonnet-latest",
                max_tokens=512,
                messages=messages,
                timeout=60,
            )
        except anthropic.AuthenticationError as e:
            # 401：不要重试，先修 Key / OAuth / 环境变量
            raise
        except anthropic.PermissionDeniedError as e:
            # 403：一般也不要重试，检查权限或模型访问
            raise
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            sleep = min(30, 2 ** attempt) + random.random()
            time.sleep(sleep)
        except (anthropic.APIConnectionError, anthropic.APITimeoutError) as e:
            if attempt == max_retries:
                raise
            sleep = min(20, 2 ** attempt) + random.random()
            time.sleep(sleep)
        except anthropic.APIStatusError as e:
            if e.status_code in [500, 529] and attempt < max_retries:
                time.sleep(min(20, 2 ** attempt) + random.random())
                continue
            raise

重试策略可以这样定

错误	是否重试	建议策略
400	否	修请求格式、模型名或参数
401	否	检查 API Key、OAuth、环境变量
403	否	检查权限、模型访问和账户状态
413	否	减小请求体或拆分文件
429	是	等待、限流、减少 token
timeout	视情况	退避、开启 stream、拆任务
500	是	指数退避后重试
529	是	退避、降级模型，稍后再试

排查 checklist：报错后 5 分钟内先做什么？

报错现场先收集这些信息

记录完整的 error.message；
记录 status code 和 error.type；
记录 request-id；
用 curl 发最小请求验证 Key；
分清楚当前用的是 Anthropic 官方 API、Claude Code、Bedrock，还是第三方兼容平台；
看看是不是只有某个模型失败；
检查请求里是否包含长上下文、大文件，或者过大的 max_tokens；
查看并发数和重试次数；
检查有没有出现重试风暴；
看服务状态页或平台公告，确认是否有已知故障。

生产环境可以提前做这些预防

Key 只放后端，不要放到前端；
日志要脱敏，不记录完整 Key 和敏感 prompt；
针对 429 建立队列和限流；
给每个模型设置 token 预算；
配置合理的 timeout；
重试要有次数上限和总耗时预算；
监控 401、429、timeout、529 的比例变化；
保存 request-id，方便后续联系支持；
使用第三方平台时，确认 base URL、鉴权字段和配额规则。

其他 Claude API 错误码简单速查

状态码	常见类型	是否重试	主要处理方式
400	`invalid_request_error`	否	检查 JSON、参数、模型名和消息格式
401	`authentication_error`	否	检查 Key、OAuth、header
403	`permission_error`	否	检查权限、账户状态和模型访问
404	`not_found_error`	否	检查 URL、资源和 endpoint
413	`request_too_large`	否	减小请求体，拆分文件
429	`rate_limit_error`	是	限流、等待、减少 token
500	`api_error`	是	退避重试，并保留 request-id
529	`overloaded_error`	是	稍后重试，必要时降级模型

FAQ

Claude API 401 是不是说明账号被封了？

不一定。更常见的原因是 Key 没传、环境变量没读到、header 写错、OAuth 过期，或者第三方工具配置错了。先用 curl 发一个最小请求验证，不要直接下结论。

Claude Max 订阅能不能直接当 API 用？

不能简单这么理解。Claude Web / Claude Max 和 API Key、API 额度是不同体系。API 调用通常需要在对应控制台创建 Key，并配置计费或权限。

为什么我感觉没达到限制，却还是报 429？

因为 429 不一定是 RPM。它可能是 input TPM、output TPM、日限额、模型级限制、短时间突增限制，或者第三方平台自己的配额。历史消息、文件内容、工具定义也会一起计入 token。

429 和 529 到底有什么区别？

429 通常表示你的组织、账号、模型或平台配额触发了限制；529 更偏向服务端临时过载。处理方式也不同：429 要限流、排队、减少 token；529 更适合退避、降级模型，或者稍后再试。

stream 已经返回 200，后面又断开了，这算什么？

这可能是 SSE 流式过程中断，也可能是流内错误。代码里要捕获 stream 异常，保存 partial output，记录 request-id，然后根据业务是否幂等来决定要不要重试。

Bedrock 上的 Claude 429 和 Anthropic 官方 API 的 429 一样吗？

不完全一样。Bedrock 使用的是 AWS 侧的 IAM、区域、模型配额和限流规则，不能只看 Anthropic 官方 API 的限制。第三方兼容平台也是同理，最好查看对应平台自己的说明。# Claude API 常见报错排查：401、429、超时到底怎么处理？

说明：本文提到的“Claude API”，主要指 Anthropic 原生 API，以及一些兼容 Anthropic API 的接入方式。如果你用的是 Claude Code、AWS Bedrock、OpenRouter、TypingMind、ClaudeAPI 这类第三方工具或兼容平台，那么错误码有可能被平台重新包装过。具体的限制、计费、线路、模型支持情况，还是要以对应平台的最新说明为准。另外，ClaudeAPI 是第三方 Claude API 兼容接入服务平台，并不是 Anthropic 官方服务。

先说结论：401、429、超时分别该怎么处理？

报错现象	最可能的原因	先做什么	要不要重试
401 `authentication_error`	API Key 缺失、无效，OAuth 过期，或者代理把 header 丢了	先用 curl 发一个最小请求验证 Key	不建议
429 `rate_limit_error`	RPM、TPM、日限额、模型额度或平台配额超了	先看 `error.message`，判断到底是哪类限制	可以，但必须退避
请求超时 timeout	网络、代理、生成太慢、上下文太长、网关超时	先区分是连接超时、读取超时，还是总超时	看情况
529 `overloaded_error`	服务端临时过载	指数退避、稍后再试，必要时降级模型	可以

简单理解就是：

401 不要一上来就重试，这类问题大多是认证没配对，先修 Key、header 或登录态。
429 也不是简单加个 sleep 就完事，要先判断是请求数超了，还是 token 用得太猛。
timeout 不一定是 Claude API 返回的错误，它可能发生在 SDK、代理、Serverless、Nginx，甚至浏览器这一层。
429 和 529 不是一回事：429 通常跟你的账号、组织、模型或平台配额有关；529 更像是服务端一时扛不住了。

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

Claude API 报错时，通常会返回类似下面这样的结构：

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

排查时不要只截一张“报错了”的图，最好把下面这些信息都记下来：

HTTP status，比如 401、429、500、529；
error.type，比如 authentication_error、rate_limit_error；
error.message，这里往往会写清楚认证失败或限流的具体原因；
request-id / x-request-id；
使用的 model；
是否开启 stream；
输入长度、历史对话轮数、文件大小、预估 token；
max_tokens 设置；
retry 次数；
latency，也就是耗时；
provider：到底是 Anthropic 官方 API、Bedrock、Claude Code，还是第三方兼容平台。

401 authentication_error：先查 API Key、OAuth 和环境变量

401 一般代表什么？

Claude API 返回 401，通常就是认证出了问题。常见原因有这些：

API Key 根本没传；
API Key 写错、失效、被删除，或者复制时带了空格和换行；
环境变量没有被当前进程读取到；
header 写错了；
代理、网关、Cloudflare Worker、Nginx 转发时把 x-api-key 丢掉了；
Claude Code 使用的 OAuth token 过期；
把 Claude Max / Claude Pro 订阅误以为是 API Key；
第三方工具里的 provider、base URL 或鉴权字段配错了。

第一步：先用 curl 验证 Key 是否真的可用

不要一开始就在业务代码里绕来绕去。最稳妥的做法，是先绕过你的项目代码，用一个最小请求测试 Key：

curl 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-3-5-sonnet-latest",
    "max_tokens": 32,
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

如果这个 curl 请求都返回 401，那就优先检查下面几件事：

$ANTHROPIC_API_KEY 是不是空的；
Key 是否是在 Console 里正确创建的；
复制 Key 时有没有多带空格、换行或引号；
当前账户或项目是否已经具备 API 使用条件；
有没有把 Claude Web 登录态、Claude Max 订阅当成 API Key 来用。

这里也提醒一下，不要用浏览器直接打开 API 地址来判断能不能用，更不要把完整 Key 打进日志或者发到论坛、群聊里。

第二步：检查代码里的认证写法

Anthropic 原生 API 常用的是 x-api-key，通常还需要带上 anthropic-version。不少从 OpenAI SDK 或 OpenAI 接口迁移过来的用户，会习惯性写成：

Authorization: Bearer sk-xxx

但在 Anthropic 原生 API 场景下，这通常不是正确写法。原生 HTTP header 一般类似这样：

x-api-key: your_api_key
anthropic-version: 2023-06-01
content-type: application/json

第三步：别忽略 `.env`、Docker 和 CI/CD

很多时候，Claude API 401 并不是 Key 真失效了，而是程序根本没有读到这个 Key。常见坑包括：

.env 文件改了，但服务没有重启；
变量名写成了 CLAUDE_API_KEY，而 SDK 实际读取的是 ANTHROPIC_API_KEY；
Docker Compose 没有把 secret 注入容器；
GitHub Actions 里创建了 secret，但没有映射到 job 的 env；
本地 shell 有变量，生产环境的进程却没有；
Key 前后带了引号、空格或换行；
前端代码尝试直接调用 API，结果 Key 暴露，或者被浏览器环境限制。

排查时可以打印 Key 的长度，但不要打印完整 Key：

import os

key = os.getenv("ANTHROPIC_API_KEY")
print("key exists:", bool(key), "length:", len(key or ""))

这样既能确认变量有没有读到，也不会把敏感信息泄露出去。

Claude Code、Claude Max、第三方工具里的 401 有什么区别？

这里很容易混淆，建议把几个入口分清楚：

Anthropic API Key：一般在 Console 里创建，用于 API 调用；
Claude Web / Claude Max / Pro：这是网页端或订阅服务，不等同于 API Key，也不等同于 API 额度；
Claude Code：可能使用 OAuth 登录，也可能配置 API Key 或 Bedrock；
AWS Bedrock：走的是 AWS IAM、区域和 Bedrock 配额，不使用 Anthropic API Key；
第三方工具或兼容平台：往往有自己的鉴权字段、base URL、限流规则和错误包装。

429 rate_limit_error：并不只是“请求太快了”

429 常见原因有哪些？

Claude API 返回 429，意思是触发了限制。但这个限制不一定是“请求太频繁”，也可能是 token、预算、模型或平台层面的限制。常见情况包括：

RPM，也就是每分钟请求数超限；
input TPM，每分钟输入 token 超限；
output TPM，每分钟输出 token 超限；
单次请求的上下文太长；
历史消息、system prompt、工具定义、上传文件叠加后 token 过大；
日限额、预算或 usage tier 限制；
模型级别的限制；
组织级别的限制；
短时间流量突然上涨，触发 acceleration limit；
Bedrock、OpenRouter、ClaudeAPI 等平台自己的配额或限流。

怎么从错误信息判断是哪种 429？

优先看 error.message 里的关键词：

message 关键词	可能含义	优先怎么处理
`requests per minute`	RPM 超限	降并发、排队、令牌桶
`input tokens per minute`	输入 TPM 超限	减少上下文、拆分请求
`output tokens per minute`	输出 TPM 超限	降低 `max_tokens`
`daily limit`	日限额或预算限制	等额度恢复，或调整预算
`too many tokens`	单次请求或窗口 token 太大	压缩 prompt、拆分文档
只写 `rate limit`	泛化限流	结合日志、响应头和控制台一起看

要注意的是，一次请求里的 token 不只是你当前发的那句话。历史对话、system prompt、工具 schema、文件内容、检索结果，都会一起计入。

如果是请求数超限，该怎么限流？

如果 429 是请求数超限，千万不要“失败后立刻重试”。这很容易把系统打成重试风暴，越重试越失败。更稳的做法是：

降低 worker 并发；
引入任务队列；
按模型维度做限流；
使用令牌桶或漏桶；
多实例服务使用共享限流状态；
批量任务做削峰填谷；
避免每个请求各自无限重试。

换句话说，429 不是简单睡一秒就能解决的。你需要让请求进入一个可控的节奏里。

如果是 token 超限，该怎么减少 token？

如果是 token 相关的限制，就要从请求内容本身下手：

多轮对话只保留最近 N 轮；
对较早的上下文做摘要；
压缩 system prompt；
精简工具定义；
大文件先抽取关键段落，再送进模型；
长文档拆分处理；
降低 max_tokens；
给不同模型设置不同的 token 预算；
在日志里记录历史轮数、prompt 长度、文件大小和预估 token。

很多 429 看起来像“调用太频繁”，实际上是上下文太肥了。尤其是带文件、检索结果、工具调用的场景，更要注意 token 预算。

429 到底该怎么重试？

429 可以重试，但一定要有边界，不能无脑重试。比较合理的策略是：

优先尊重 retry-after；
如果没有 retry-after，就使用指数退避；
加入 jitter，避免所有请求同一时间恢复；
设置最大重试次数；
设置总超时预算；
高并发场景必须配合队列和限流；
401、403、400 这类错误通常不要重试。

可以按下面这个思路处理：

if status in [401, 403, 400]:
    fail fast
elif status == 429:
    wait retry-after or exponential_backoff_with_jitter
elif status in [500, 529] or timeout:
    retry with backoff
else:
    inspect error

timeout 超时：先分清连接超时、读取超时和流式中断

先判断是哪一种超时

类型	典型表现	常见原因	处理方向
DNS/连接超时	请求还没连上	网络、代理、DNS、防火墙	检查网络和 base URL
TLS/握手超时	HTTPS 建连失败	代理、证书、网络拦截	检查证书和代理配置
读取超时	请求发出去后长时间没响应	上下文大、生成慢	开 stream，调整 read timeout
总超时	达到客户端总耗时限制	`max_tokens` 大、任务重	拆任务，调整 total timeout
网关超时	504、函数超时	Nginx、Vercel、Lambda 限制	异步化或流式返回
流式中断	已经输出一部分后断开	网络抖动、SSE 被代理截断	保存 partial output，必要时重试

更推荐的处理方式

遇到 timeout，可以从这些方向优化：

开启 streaming，降低用户等待感；
区分 connect timeout、read timeout 和 total timeout；
降低 max_tokens；
缩短历史上下文；
把大任务拆成多个小请求；
长任务放到后台队列，前端轮询结果；
对 timeout、500、529 做有限重试；
流式响应中断时保存已经生成的内容；
确认代理层支持 SSE；
不要在浏览器端直接暴露 API Key，最好由后端转发，并加上限流和鉴权。

说白了，超时问题不一定是模型慢，也可能是你的链路里某一层等不住了。

部署环境里还有一些额外坑

如果你的服务部署在 Vercel、Netlify、Cloudflare Worker、AWS Lambda、API Gateway、Nginx 后面，还要特别留意平台自己的超时限制。比如：

Serverless 函数通常不适合长时间阻塞；
Nginx 要关注 proxy_read_timeout；
Cloudflare、API Gateway 可能会中断长连接；
SSE 需要代理正确转发，不能被缓存或缓冲卡住；
跨境网络、移动网络可能带来偶发断流。

这类问题在本地测试可能完全正常，一上生产就暴露出来，所以最好提前压测和观察日志。

可直接参考的错误处理代码模板

Python 示例：退避、限流与 request-id 思路

import random
import time
import anthropic

client = anthropic.Anthropic()

def call_claude(messages, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model="claude-3-5-sonnet-latest",
                max_tokens=512,
                messages=messages,
                timeout=60,
            )
        except anthropic.AuthenticationError as e:
            # 401：不要重试，先修 Key / OAuth / 环境变量
            raise
        except anthropic.PermissionDeniedError as e:
            # 403：一般也不要重试，检查权限或模型访问
            raise
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            sleep = min(30, 2 ** attempt) + random.random()
            time.sleep(sleep)
        except (anthropic.APIConnectionError, anthropic.APITimeoutError) as e:
            if attempt == max_retries:
                raise
            sleep = min(20, 2 ** attempt) + random.random()
            time.sleep(sleep)
        except anthropic.APIStatusError as e:
            if e.status_code in [500, 529] and attempt < max_retries:
                time.sleep(min(20, 2 ** attempt) + random.random())
                continue
            raise

重试策略可以这样定

错误	是否重试	建议策略
400	否	修请求格式、模型名或参数
401	否	检查 API Key、OAuth、环境变量
403	否	检查权限、模型访问和账户状态
413	否	减小请求体或拆分文件
429	是	等待、限流、减少 token
timeout	视情况	退避、开启 stream、拆任务
500	是	指数退避后重试
529	是	退避、降级模型，稍后再试

排查 checklist：报错后 5 分钟内先做什么？

报错现场先收集这些信息

记录完整的 error.message；
记录 status code 和 error.type；
记录 request-id；
用 curl 发最小请求验证 Key；
分清楚当前用的是 Anthropic 官方 API、Claude Code、Bedrock，还是第三方兼容平台；
看看是不是只有某个模型失败；
检查请求里是否包含长上下文、大文件，或者过大的 max_tokens；
查看并发数和重试次数；
检查有没有出现重试风暴；
看服务状态页或平台公告，确认是否有已知故障。

生产环境可以提前做这些预防

Key 只放后端，不要放到前端；
日志要脱敏，不记录完整 Key 和敏感 prompt；
针对 429 建立队列和限流；
给每个模型设置 token 预算；
配置合理的 timeout；
重试要有次数上限和总耗时预算；
监控 401、429、timeout、529 的比例变化；
保存 request-id，方便后续联系支持；
使用第三方平台时，确认 base URL、鉴权字段和配额规则。

其他 Claude API 错误码简单速查

状态码	常见类型	是否重试	主要处理方式
400	`invalid_request_error`	否	检查 JSON、参数、模型名和消息格式
401	`authentication_error`	否	检查 Key、OAuth、header
403	`permission_error`	否	检查权限、账户状态和模型访问
404	`not_found_error`	否	检查 URL、资源和 endpoint
413	`request_too_large`	否	减小请求体，拆分文件
429	`rate_limit_error`	是	限流、等待、减少 token
500	`api_error`	是	退避重试，并保留 request-id
529	`overloaded_error`	是	稍后重试，必要时降级模型

FAQ

Claude API 401 是不是说明账号被封了？

Claude Max 订阅能不能直接当 API 用？

不能简单这么理解。Claude Web / Claude Max 和 API Key、API 额度是不同体系。API 调用通常需要在对应控制台创建 Key，并配置计费或权限。

为什么我感觉没达到限制，却还是报 429？

429 和 529 到底有什么区别？

stream 已经返回 200，后面又断开了，这算什么？

Bedrock 上的 Claude 429 和 Anthropic 官方 API 的 429 一样吗？

不完全一样。Bedrock 使用的是 AWS 侧的 IAM、区域、模型配额和限流规则，不能只看 Anthropic 官方 API 的限制。第三方兼容平台也是同理，最好查看对应平台自己的说明。

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

2601_96343664

@2601_96343664

已为社区贡献3条内容

Claude API Key 在哪获取？申请步骤详解

2601_96343664

Claude API 常见报错排查：401、429、超时到底怎么处理？

先说结论：401、429、超时分别该怎么处理？

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

401 authentication_error：先查 API Key、OAuth 和环境变量

401 一般代表什么？

第一步：先用 curl 验证 Key 是否真的可用

第二步：检查代码里的认证写法

第三步：别忽略 .env、Docker 和 CI/CD

Claude Code、Claude Max、第三方工具里的 401 有什么区别？

429 rate_limit_error：并不只是“请求太快了”

429 常见原因有哪些？

怎么从错误信息判断是哪种 429？

如果是请求数超限，该怎么限流？

如果是 token 超限，该怎么减少 token？

429 到底该怎么重试？

timeout 超时：先分清连接超时、读取超时和流式中断

先判断是哪一种超时

更推荐的处理方式

部署环境里还有一些额外坑

可直接参考的错误处理代码模板

Python 示例：退避、限流与 request-id 思路

重试策略可以这样定

排查 checklist：报错后 5 分钟内先做什么？

报错现场先收集这些信息

生产环境可以提前做这些预防

其他 Claude API 错误码简单速查

FAQ

Claude API 401 是不是说明账号被封了？

Claude Max 订阅能不能直接当 API 用？

为什么我感觉没达到限制，却还是报 429？

429 和 529 到底有什么区别？

stream 已经返回 200，后面又断开了，这算什么？

Bedrock 上的 Claude 429 和 Anthropic 官方 API 的 429 一样吗？

先说结论：401、429、超时分别该怎么处理？

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

401 authentication_error：先查 API Key、OAuth 和环境变量

401 一般代表什么？

第一步：先用 curl 验证 Key 是否真的可用

第二步：检查代码里的认证写法

第三步：别忽略 .env、Docker 和 CI/CD

Claude Code、Claude Max、第三方工具里的 401 有什么区别？

429 rate_limit_error：并不只是“请求太快了”

429 常见原因有哪些？

怎么从错误信息判断是哪种 429？

如果是请求数超限，该怎么限流？

如果是 token 超限，该怎么减少 token？

429 到底该怎么重试？

timeout 超时：先分清连接超时、读取超时和流式中断

先判断是哪一种超时

更推荐的处理方式

部署环境里还有一些额外坑

可直接参考的错误处理代码模板

Python 示例：退避、限流与 request-id 思路

重试策略可以这样定

排查 checklist：报错后 5 分钟内先做什么？

报错现场先收集这些信息

生产环境可以提前做这些预防

其他 Claude API 错误码简单速查

FAQ

Claude API 401 是不是说明账号被封了？

Claude Max 订阅能不能直接当 API 用？

为什么我感觉没达到限制，却还是报 429？

429 和 529 到底有什么区别？

stream 已经返回 200，后面又断开了，这算什么？

Bedrock 上的 Claude 429 和 Anthropic 官方 API 的 429 一样吗？

所有评论(0)

温馨提示：您尚未绑定手机号

2601_96343664

第三步：别忽略 `.env`、Docker 和 CI/CD

第三步：别忽略 `.env`、Docker 和 CI/CD