Claude Code官方文档错误Error

Claude Code 错误参考手册 - 运行时错误码与修复方法

查找 Claude Code 运行时错误消息，了解每个错误的含义以及如何修复，包括 API 错误、使用限制、身份验证、网络和请求错误。

· 阅读约 24 分钟

错误参考

查找 Claude Code 运行时错误消息，了解每个错误的含义以及如何修复。

本页列出了 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 command not found 或设置期间的 TLS 故障），请参阅故障排除安装和登录。

这些错误和恢复命令适用于 CLI、桌面应用和网络上的 Claude Code，因为这三个都包装了相同的 Claude Code CLI。对于特定于表面的问题，请参阅该表面页面上的故障排除部分。

ℹ️ Claude Code 调用 Claude API 获取模型响应，因此大多数运行时错误映射到底层 API 错误代码。本页介绍了每个错误在 Claude Code 中的含义以及如何恢复。有关原始 HTTP 状态代码定义，请参阅 Claude Platform 错误参考。

查找您的错误

将您在终端中看到的消息与下面的部分相匹配。

消息部分
API Error: 500 ... Internal server error服务器错误
API Error: Repeated 529 Overloaded errors服务器错误
Request timed out服务器错误，或如果消息提到您的互联网连接，则为网络
<model> is temporarily unavailable, so auto mode cannot determine the safety of...服务器错误
Auto mode could not evaluate this action and is blocking it for safety服务器错误
Auto mode classifier transcript exceeded context window服务器错误
You've hit your session limit / You've hit your weekly limit使用限制
Server is temporarily limiting requests使用限制
Request rejected (429)使用限制
Credit balance is too low使用限制
Not logged in · Please run /login身份验证
Invalid API key身份验证
This organization has been disabled身份验证
Routines are disabled by your organization's policy身份验证
OAuth token revoked / OAuth token has expired身份验证
does not meet scope requirement user:profile身份验证
Unable to connect to API网络
SSL certificate verification failed网络
403 with x-deny-reason: host_not_allowed in a cloud or routine session网络
Prompt is too long请求错误
Error during compaction: Conversation too long请求错误
Request too large请求错误
Image was too large请求错误
PDF too large / PDF is password protected请求错误
Extra inputs are not permitted请求错误
There's an issue with the selected model请求错误
Claude Opus is not available with the Claude Pro plan请求错误
thinking.type.enabled is not supported for this model请求错误
max_tokens must be greater than thinking.budget_tokens请求错误
API Error: 400 due to tool use concurrency issues请求错误
响应质量似乎低于平常响应质量

自动重试

Claude Code 在向您显示错误之前会重试瞬时故障。服务器错误、过载响应、请求超时、临时 429 限流和断开的连接都会以指数退避方式重试最多 10 次。重试时，微调器显示 Retrying in Ns · attempt x/y 倒计时。

当您看到本页上的错误之一时，这些重试已经用尽。您可以使用两个环境变量调整行为：

变量默认值效果
CLAUDE_CODE_MAX_RETRIES10重试次数。降低它以在脚本中更快地显示故障；提高它以等待更长的事件。
API_TIMEOUT_MS600000每个请求的超时时间（毫秒）。为慢速网络或代理提高它。

服务器错误

这些错误来自 Anthropic 基础设施，而不是您的帐户或请求。

API Error: 500 Internal server error

Claude Code 为任何 5xx 状态显示原始 API 响应体。下面的示例显示了 500 响应：

API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"}} · check status.claude.com

这表示 API 内部出现意外故障。它不是由您的提示、设置或帐户引起的。

要做什么：

  • 检查 status.claude.com 以了解活跃事件
  • 等待一分钟，然后再次发送您的消息。您的原始消息仍在对话中，因此对于长提示，您可以输入 try again 而不是粘贴整个内容。
  • 如果错误持续存在且没有发布的事件，请运行 /feedback，以便 Anthropic 可以使用您的请求详情进行调查。

API Error: Repeated 529 Overloaded errors

API 在所有用户中暂时处于容量限制。Claude Code 在显示此消息之前已经重试了多次：

API Error: Repeated 529 Overloaded errors · check status.claude.com

529 不是您的使用限制，也不会计入您的配额。

要做什么：

  • 检查 status.claude.com 以了解容量通知
  • 几分钟后重试
  • 运行 /model 并切换到不同的模型以继续工作

Request timed out

API 在连接截止时间之前没有响应。

Request timed out

这可能在高负载期间或生成非常大的响应时发生。默认请求超时为 10 分钟。

要做什么：

  • 重试请求
  • 对于长时间运行的任务，将工作分解为较小的提示
  • 如果是慢速网络或代理导致的，请按照自动重试中的说明提高 API_TIMEOUT_MS

Auto mode cannot determine the safety of an action

auto mode 用来分类操作的模型无法做出决定，因此 auto mode 没有自动批准该操作。您看到的消息取决于分类器失败的原因。

在您的工作目录中的读取、搜索和编辑会跳过分类器，因此它们在所有这些情况下都继续工作。

当分类器模型过载时：

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

当分类器返回无法解析的响应时：

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

当对话增长超过分类器的上下文窗口时：

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

使用限制

这些错误意味着与您的帐户或计划相关的配额已达到。

You’ve hit your session limit

订阅计划包括滚动使用额度。当它用完时，您会看到以下消息之一：

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Claude Code 阻止进一步的请求，直到消息中显示的重置时间。

要做什么：

  • 等待错误中显示的重置时间
  • 运行 /usage 以查看您的计划限制以及它们何时重置
  • 运行 /extra-usage 以在 Pro 和 Max 上购买额外使用，或在 Team 和 Enterprise 上向您的管理员请求
  • 要升级您的计划以获得更高的基础限制，请参阅 claude.com/pricing

Server is temporarily limiting requests

API 应用了与您的计划配额无关的短期限流。

API Error: Server is temporarily limiting requests (not your usage limit)

Request rejected (429)

您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。

API Error: Request rejected (429) · this may be a temporary capacity issue

要做什么：

  • 运行 /status 并确认活跃凭证是您期望的凭证
  • 检查您的提供商控制台以了解活跃限制
  • 降低并发：降低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，避免运行许多并行子代理

Credit balance is too low

您的 Console 组织已用完预付信用。

Credit balance is too low

要做什么：

  • 在 platform.claude.com/settings/billing 添加信用
  • 如果您有 Pro、Max、Team 或 Enterprise 计划，请使用 /login 切换到订阅身份验证
  • 在 Console 中设置每个工作区的支出上限

身份验证错误

这些错误意味着 Claude Code 无法向 API 证明您的身份。随时运行 /status 以查看当前活跃的凭证。

Not logged in

此会话没有有效的凭证可用。

Not logged in · Please run /login

要做什么：

  • 运行 /login 以使用您的 Claude 订阅或 Console 帐户进行身份验证
  • 如果您期望环境变量对您进行身份验证，请确认 ANTHROPIC_API_KEY 已在您启动 claude 的 shell 中设置和导出

Invalid API key

ANTHROPIC_API_KEY 环境变量或 apiKeyHelper 脚本返回了 API 拒绝的密钥。

Invalid API key · Fix external API key

要做什么：

  • 检查拼写错误，并确认密钥未在 Console 中被撤销
  • 在同一 shell 中运行 env | grep ANTHROPIC
  • 取消设置 ANTHROPIC_API_KEY 并运行 /login 以改用订阅身份验证

This organization has been disabled

来自禁用的 Console 组织的过时 ANTHROPIC_API_KEY 正在覆盖您的订阅登录。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials

环境变量优先于 /login，因此在您的 shell 配置文件中导出或从 .env 文件加载的密钥即使您有有效的 Pro 或 Max 订阅也会被使用。

Routines are disabled by your organization’s policy

您的团队或企业管理员已在组织级别关闭了例程。

Routines are disabled by your organization's policy.

OAuth token revoked or expired

您保存的登录不再有效。

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login
API Error: 401 ... authentication_error

要做什么：

  • 运行 /login 以再次登录
  • 如果在重新身份验证后错误在同一会话中返回，请先运行 /logout 以完全清除存储的令牌

OAuth scope requirement

存储的令牌早于较新功能所需的权限范围。

OAuth token does not meet scope requirement: user:profile

要做什么：

  • 运行 /login 以使用当前范围铸造新令牌

网络和连接错误

这些错误意味着来自 Claude Code 的网络请求无法到达其目的地。

Unable to connect to API

到 API 的 TCP 连接失败或从未完成。

Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API (ECONNRESET)
Unable to connect to API (ETIMEDOUT)
fetch failed
Request timed out. Check your internet connection and proxy settings

要做什么：

  • 通过从同一 shell 运行 curl -I https://api.anthropic.com 来确认您可以到达 API 主机
  • 如果您在公司代理后面，请在启动 Claude Code 之前设置 HTTPS_PROXY 并参阅网络配置
  • 如果您通过 LLM 网关或中继路由，请将 ANTHROPIC_BASE_URL 设置为其地址
  • 确保您的防火墙允许网络访问要求中列出的主机

SSL certificate errors

您网络上的代理或安全设备正在使用其自己的证书拦截 TLS 流量。

Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detected

要做什么：

  • 导出您组织的 CA 包并使用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 指向 Claude Code
  • 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，这会完全禁用证书验证

Host not allowed in a cloud session

来自云会话或例程的出站 HTTP 请求被环境的网络策略阻止。

HTTP 403
x-deny-reason: host_not_allowed

要做什么：

  • 打开例程进行编辑，或启动云会话
  • 在 Update cloud environment 对话框中，将 Network access 从 Trusted 更改为 Custom，然后将被阻止的域添加到 Allowed domains

请求错误

这些错误意味着 API 收到了您的请求但拒绝了其内容。

Prompt is too long

对话加上附加文件超过了模型的上下文窗口。

Prompt is too long

要做什么：

  • 运行 /compact 以总结早期轮次并释放空间，或运行 /clear 以重新开始
  • 运行 /context 以查看消耗窗口的内容的分解
  • 使用 /mcp disable <name> 禁用您未使用的 MCP 服务器
  • 修剪大型 CLAUDE.md 内存文件

Error during compaction: Conversation too long

/compact 本身失败，因为没有足够的可用上下文来保存它生成的摘要。

Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

Request too large

原始请求体在标记化之前超过了 API 的字节限制。

Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

Image was too large

粘贴或附加的图像超过了 API 的大小或尺寸限制。

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

PDF errors

您附加的 PDF 无法处理。

PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.

Extra inputs are not permitted

Claude Code 和 API 之间的代理或 LLM 网关删除了 anthropic-beta 请求标头。

API Error: 400 ... Extra inputs are not permitted ... context_management

要做什么：

There’s an issue with the selected model

配置的模型名称未被识别或您的帐户缺少对它的访问权限。

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to select a different one.

Claude Opus is not available with the Claude Pro plan

您的活跃订阅计划不包括您选择的模型。

Claude Opus is not available with the Claude Pro plan · Select a different model in /model

thinking.type.enabled is not supported for this model

您的 Claude Code 版本早于 Opus 4.7 的最低版本。

API Error: 400 ... "thinking.type.enabled" is not supported for this model.

要做什么：

  • 运行 claude update 以升级到 v2.1.111 或更高版本

Thinking budget exceeds output limit

配置的扩展思考预算超过了最大响应长度。

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

Tool use or thinking block mismatch

对话历史以不一致的状态到达 API。

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

要做什么：

  • 运行 /rewind，或按 Esc 两次

响应质量似乎低于平常

如果 Claude 的答案似乎不如您期望的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。

首先检查这些：

  • 模型选择：运行 /model 以确认您在期望的模型上
  • 努力级别：运行 /effort 以检查当前推理级别
  • 上下文压力：运行 /context 以查看窗口有多满
  • 过时的说明：大型或过时的 CLAUDE.md 文件和 MCP 工具定义消耗上下文并可能引导响应

当响应出错时，回退通常比用更正回复效果更好。按 Esc 两次或运行 /rewind 以回退到坏轮次之前。

如果在检查上述内容后质量仍然似乎有问题，请运行 /feedback 并描述您期望的内容与您得到的内容。

报告错误

本页涵盖来自 Claude API 的错误。对于来自其他 Claude Code 组件的错误，请参阅相关指南：

如果此处未列出错误或建议的修复无法帮助：

  • 在 Claude Code 中运行 /feedback 以将记录和描述发送给 Anthropic
  • 运行 /doctor 以检查本地配置问题
  • 检查 status.claude.com 以了解活跃事件
  • 在 GitHub 上搜索现有问题

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。