Claude API 报错 The operation timed out（请求超时）：原因与解决办法

Claude API 报错「API Error: The operation timed out」，意思是这次请求在拿到可用响应之前就到了超时时限。它不是认证错误，也不是余额问题。在 Claude Code 里，单次请求的时限由 API_TIMEOUT_MS 控制，默认 10 分钟；你看到这条报错时，Claude Code 已经自动重试过了。多数情况下要改的是网络、代理或网关设置，而不是提示词。

本文讲清楚这个超时到底在计什么时、它和几个长得很像的报错怎么区分，以及该按什么顺序改哪些设置。文中关于 Claude Code 与 Claude API 的事实均出自官方文档 code.claude.com 与 platform.claude.com，核实日期 2026-09-26。

Claude API 报错「the operation timed out」到底是什么意思

超时是你这一侧的计时器走完了，不是模型给出的结论。Claude Code 官方错误参考里对应的条目叫 Request timed out：在连接时限内 API 没有给出响应。官方列出的两类常见原因是：高负载时段，或者模型正在生成一段很长的回答。默认请求超时是 10 分钟。

由此可以推出两点：

• 你的凭据是好的。 key 有问题会很快返回 401 或 403，并带 JSON 错误体。超时说明请求已经走到「在等响应」这一步。拿不准时，可以对照 Anthropic API Key 用不了？先读状态码 区分。
• 链路上有一环太慢或不出声了。 可能是模型在写长回答，可能是网络慢，也可能是某个代理或网关要等响应全部生成完才往回转发。

超时、504、No response from API、流中断：先认清是哪一个

几条报错看着像，指向的却是不同层。改设置之前先看清原文。

最关键的区分：504 timeout_error 是 API 告诉你它那边超时了，而「the operation timed out」是你的客户端先放弃了。两者的解决办法不同。

报错出现之前，Claude Code 已经做了什么

看到这条报错时，重试次数已经用完了。按官方错误参考：

• 对瞬时故障（包括在 Claude 的回答还没开始流式返回之前发生的请求超时），Claude Code 会以指数退避最多重试 10 次。CLAUDE_CODE_MAX_RETRIES 可以改这个次数。
• 挂起中的流如果 20 秒没有任何数据，界面会显示 Waiting for API response · will retry in … · check your network。此时请求还没有失败。
• 直连 Anthropic API 时，一个始终收不到响应头的流式请求会在首字节时限被中止（直连 API 为 180 秒，其他情况 300 秒，另按请求体每 32KB 加 1 秒），然后重发一次，而不是干等满 10 分钟。文档注明：当 ANTHROPIC_BASE_URL 把请求路由到网关时，这个首字节时限不生效，这类连接会一直等到 API_TIMEOUT_MS。

所以「再试一次」这件事其实已经替你做过一部分了。如果报错反复出现，先改点什么再重试。

按顺序排查和修复

1. 先重试一次，然后把任务拆小

高负载时偶发的一次超时往往会自己消失。同一个任务反复超时时，官方建议把长任务拆成更小的提示：要求一次性输出超长回答，正是最容易撞到 10 分钟时限的情况。

2. 在同一个终端里检查网络链路

在你启动 Claude Code 的那个终端里做一次连通性检查：

curl -I https://api.anthropic.com

Windows PowerShell 下请用 curl.exe，避免调用到内置别名。如果这一步就失败，先解决网络：VPN、防火墙、DNS，或者需要设置 HTTPS_PROXY 的企业代理。「代理」的两种含义见 Claude Code 代理配置。

如果检查通过、Claude Code 仍然超时，看看是否残留了 ANTHROPIC_BASE_URL。设置了它之后，Claude Code 会把模型请求发到那个地址而不是 api.anthropic.com；如果它指向一个很慢或已经不在的中转，就会出现上面的检查能通、Claude Code 却一直失败的情况。

3. 代理或网关会攒住响应时，调大超时

有些代理和网关要等回答全部生成完才转发。回答一长，这段沉默就可能超过客户端的等待上限。官方给出的办法是调大单次请求超时，单位是毫秒，默认 600000：

export API_TIMEOUT_MS=900000

想长期生效、不必每次手动 export，就写进 settings 文件的 env 块：~/.claude/settings.json 对所有项目生效，.claude/settings.local.json 只对当前项目生效：

{
  "env": {
    "API_TIMEOUT_MS": "900000"
  }
}

参考文档里有两点提醒：超过 2147483647 的值会让计时器溢出，请求立刻失败；小于 11 秒的正值会关闭首字节时限。如果第一次尝试总是超时、重试却能成功，可以单独调 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS（需要 Claude Code v2.1.242 及以上，取值会被限制在 10 秒到 30 分钟之间）。同一个键在几层 settings 里都出现时谁生效，见 Claude Code 配置：分几层、怎么合并。

4. 确认改动真的生效

改完后开一个新会话，运行 /status 看当前用的端点和设置来源。写错层的值不会报任何错，所以要看实际生效的值，而不是重读你刚改的那个文件。

如果你是在自己的代码里直接调 Claude API

在 Claude Code 之外，同样的报错文本经常来自你的 HTTP 客户端或 SDK。Claude API 文档对长请求的建议很具体：

• 耗时长的请求，尤其是超过 10 分钟的，改用 流式 Messages API 或 Message Batches API。
• 不开流式时，不要设置过大的 max_tokens。有些网络会在不固定的时间后断开空闲连接，导致请求失败，或在没收到 Anthropic 任何响应的情况下超时。
• 官方 SDK 会检查非流式 Messages 请求是否预计会超过 10 分钟的超时，并设置 TCP keep-alive。不用 SDK 的直接集成，可以自己设置 keep-alive。
• API 真的返回 504 timeout_error 时，处理方式相同：改为流式，或者把任务挪到批处理。

流式并不会让生成变快，它的作用是让字节持续流动，链路上的空闲计时器就不会触发。延迟上的取舍见 LLM API 延迟。

链路里有中转或网关时

每一跳都有自己的计时器：你的客户端、企业代理、网关、上游 API。最短的那一个决定请求什么时候断。通过中转端点调用时：

• 让客户端超时与网关超时匹配。客户端时限比网关还长，只意味着你要多等一会儿才拿到网关的报错。
• 尽量端到端使用流式。网关边收边转发流事件，空闲计时器就不会触发；网关把事件攒起来再转，问题就又回来了。
• 读一下失败响应的正文。HTML 错误页或非 Claude 格式的错误体，来自 API 前面的某一跳，而不是 Messages API 本身。

常见问题

「API Error: The operation timed out」是 API Key 的问题吗？

不是。被拒绝的 key 会很快返回 401 或 403。超时说明请求已经被接收到「等待响应」这一步，只是响应没有按时到达。

Claude Code 默认超时是多少？

API_TIMEOUT_MS 默认 600000 毫秒，也就是 10 分钟；Claude Code 在显示报错前会对瞬时故障最多重试 10 次。

怎么调大 Claude Code 的超时？

设置 API_TIMEOUT_MS（单位毫秒），可以在 shell 里 export，也可以写进 settings 文件的 env 块。网络慢、或代理与网关会攒住响应时再调大，不要超过 2147483647。

这和 MCP 服务器超时是一回事吗？

不是。MCP 服务器启动有自己的时限 MCP_TIMEOUT，默认 30 秒。MCP 超时的报错会点名具体服务器，而不是 API。

让端点保持可预期

反复出现的超时，多数出在链路而不是模型：一个攒响应的代理、一个时限很短的网关，或者一个没人记得设过的 base URL。ROIBest AI 以 Anthropic 兼容与 OpenAI 兼容端点提供 Claude 模型，通过它路由 Claude Code 或你自己的代码时，上面这些变量照样适用。把 base URL、凭据和超时放在同一层 settings 里，再用 /status 确认。