Source: https://aiprimetech.io/zh/claude-code/errors/ [首页](/zh/) › [Claude Code](/claude-code/zh/) › 错误 [概览](/claude-code/zh/)[安装](/claude-code/zh/install/)[CLI 参考文档](/zh/claude-code/cli/)[定价与限制](/claude-code/zh/pricing/)[Agent SDK](/zh/claude-code/sdk/)[技能与插件](/zh/claude-code/skills/)[GitHub](/zh/claude-code/github/)[网页、桌面与 IDE](/zh/claude-code/web-and-desktop/)[模型](/zh/claude-code/models/)[错误](/zh/claude-code/errors/)[是否开源？](/zh/claude-code/open-source/)[教程](/claude-code/zh/tutorial/)[学生指南](/zh/claude-code/for-students/)[QA 自动化](/zh/claude-code/qa-automation/)[与 Cursor 对比](/zh/claude-code/vs-cursor/)[与 Codex 和 OpenCode 对比](/zh/claude-code/vs-codex/)[子智能体](/zh/claude-code/subagents/)[钩子](/zh/claude-code/hooks/)[MCP](/zh/claude-code/mcp/)[生态系统](/zh/claude-code/ecosystem/)[VS Code](/zh/claude-code/vscode/)[OpenRouter](/zh/claude-code/openrouter/)[速率限制](/zh/claude-code/rate-limits/)[中文指南](/claude-code/zh/) 最后更新：2026 年 11 月 # Claude Code 错误及修复方法 Claude Code 会在 API 错误消息中显示 HTTP 状态，因此这个数字就能说明大部分情况。下面介绍各个状态在智能体会话中的含义，以及真正有效的修复方法。 ## TLDR - 500 / 529 — 模型端发生故障或已满载；采用退避策略重试，切换模型，无需修复你的配置。 - 400 — 通常是上下文超出了模型的容量；使用 /compact 或 /clear，或切换到上下文容量为 1M 的变体。 - 429 — 速率限制；Claude Code 的并行流会先触及并发限制。 - 401 — 密钥与端点不匹配；例如将控制台密钥用于网关 URL，或反过来。 - 使用量限制 / 每周限制 — 这是订阅的使用周期限制，并非 API 错误；它会自动重置，API 接入方式没有这种周期限制。 ## 各类错误的详细指南 - [API 错误：500（服务器内部错误）](/zh/claude-code/errors/api-error-500/) — 服务中断、特定模型故障、在 0% 时压缩上下文。 - [过载 / API 错误 529](/zh/claude-code/errors/overloaded-529/) — 容量、重试、子智能体突发请求。 - [API 错误 400](/zh/claude-code/errors/api-error-400/) — 提示词过长、工具使用并发，以及其他被拒绝的请求。 - [OAuth 错误](/zh/claude-code/errors/oauth-error/) — 超过 15000ms 超时时间，登录时出现状态码 500。 - [进程退出，退出码为 1](/zh/claude-code/errors/process-exited-code-1/) — VS Code 扩展和桌面应用崩溃。 - [已达速率限制 / 429](/zh/claude-code/rate-limits/) — 三种限制及其提高方法。 - [提示词过长 / 已达上下文上限](/zh/claude-code/errors/prompt-too-long/) — 哪些内容占满上下文窗口、误报、压缩失败、claude.ai 长度限制。 - [使用量已达上限](/zh/claude-code/errors/usage-limit-reached/) — 会话、每周和 Opus 使用周期限制，“指定的 API 使用量限制”、“额度余额过低”。 - [401 / 403 身份验证](/zh/claude-code/errors/auth-401-403/) — 凭据无效、API 密钥无效、“未登录”、host_not_allowed。 - [连接错误](/zh/claude-code/errors/connection-lost/) — ECONNRESET、“正在等待 API 响应”、证书、代理、重试变量。 - [卡住、停滞、无响应](/zh/claude-code/errors/claude-code-hangs/) — 卡在哪里、退出按键、已知卡死问题、内存。 - [claude.ai 无法使用](/zh/claude-code/errors/claude-ai-not-working/) — “出了点问题”、容量限制、5 小时限制、登录错误。 ## API 错误 500（以及 529 过载） 500 表示上游故障；529 是 Anthropic 明确表示“模型容量已满”的状态码。两者都不是由你的提示词引起的。Claude Code 会自行重试几次；如果它放弃重试，请稍等片刻，然后使用以下命令恢复会话 claude -c。使用以下命令切换模型档位 /model 通常会立即奏效，因为容量按模型划分。在此网关上，当某个上游账户满载时，会自动切换到其他账户，因此这里出现 529 错误的频率比直接使用单个账户更低。 ## API 错误 400 — 请求无效 / 上下文过长 在 Claude Code 中，400 几乎总是意味着对话加上它已读取的文件不再能容纳于模型的上下文窗口中。 /compact 会总结历史记录； /clear 会重新开始；也可以切换到模型的 (1M) 变体。其他 400 错误：升级后出现不受支持的参数（运行 claude update），或模型无法接受的图像或文件。 ## API 错误 429 — 速率限制 / 超出速率 有三种限制：每分钟请求数、每分钟 token 数和并发请求数。智能体会话会先触及并发限制 — 每个子智能体都是一个并行流式请求，会一直占用一个名额，直到请求结束。减少并行任务，等待 retry-after 指定的时间过去；如果需要持续工作，可申请提高网关账户的并发额度。 ## OAuth 错误：超过 15000ms 超时时间 /login 流程未能在 15 秒内连接到 Anthropic 的身份验证服务。这是网络问题，而非账户问题：可能是企业代理、丢弃回调的 VPN，或所在地区访问身份验证端点较慢。重试一次；如果问题仍然存在，请根据你的网络设置 HTTPS_PROXY，或使用 API 密钥完全跳过 OAuth — 设置 ANTHROPIC_API_KEY（网关还需设置 ANTHROPIC_BASE_URL）后，Claude Code 就完全不会打开登录流程。 ## OAuth 错误：请求失败，状态码为 500 身份验证服务在登录或刷新令牌时返回了服务器错误。这并非由你这边的问题引起；等待几分钟，然后再次运行 /login。如果需要立即工作，上述 API 密钥接入方式可以绕过 OAuth，而运行 claude setup-token 于能够正常登录的机器上，会生成一个长期有效的令牌，你可以将其转移到无法登录的机器上。 ## 错误：Claude Code 进程退出，退出码为 1 这表示 IDE 扩展或桌面应用报告它启动的 CLI 在启动时崩溃 — 真正的错误在下一层。打开终端，直接运行 claude ：你会看到实际的错误消息，原因几乎总是 Node.js 版本低于 18、npm 安装后 PATH 损坏、原生安装损坏，或 settings.json 中存在无效的 JSON（hooks 块中多余的逗号就是典型情况）。 claude doctor 会检查前三项；JSON 检查工具可以发现第四项。使用原生安装程序重新安装，可以解决其余大多数问题。 ## 401 / 身份验证错误 invalid x-api-key 或 authentication_error 表示密钥不属于该端点。如果 ANTHROPIC_BASE_URL 指向网关，密钥就必须是网关密钥；Anthropic 控制台密钥会被拒绝，反过来也一样。 /status 会显示当前生效的端点和密钥。如果你同时使用 /login 和 API 密钥，会优先使用密钥。令牌刷新循环、 Not logged in 成功登录后出现的情况，以及代理返回的 403 错误，请参阅 [401 / 403 页面](/zh/claude-code/errors/auth-401-403/). ## “无可用上游” 这不是 API 错误：它是服务前端的负载均衡器在报告没有可用的后端。官方端点返回此消息表示服务中断；网关返回此消息则表示整个上游池都不可用或受到限流。等待后重试；不要更改配置。 ## Claude Code 完全无法使用 - 启动后无提示退出 → 运行 claude /doctor；通常是 Node 版本或 PATH 问题。 - 启动时或会话中途卡住 → 请参阅 [卡住与停滞的会话](/zh/claude-code/errors/claude-code-hangs/) 和 [连接错误](/zh/claude-code/errors/connection-lost/). - command not found → 请参阅安装指南。 - 工具因权限错误而失败 → /permissions，或 --allowedTools 用于脚本中。 ## 厌倦了与这个问题反复较劲？ 改为通过 AI Prime Tech 网关运行 Claude Code：使用相同的 Claude 模型，由网关自己的上游账户提供服务，设置两个环境变量即可切换，新账户可获得 $5 免费 API 额度 使用优惠码 FIXIT — 无需银行卡。 ``` export ANTHROPIC_BASE_URL=https://aiprimetech.io export ANTHROPIC_API_KEY=your_key ``` [使用优惠码 FIXIT 创建账户](/register?promo=FIXIT) ## 常见问题 为什么 Claude Code 一直返回 API 错误 500？ 模型后端发生故障或过载（529 是明确表示过载的状态码）。稍等后重试，使用 /model 切换模型档位，或使用 claude -c 恢复会话。这不是你的配置问题。如何修复 Claude Code 错误 400：上下文长度问题？ 运行 /compact 来总结会话，运行 /clear 来重置，或切换到上下文容量为 1M 的模型版本。为什么 Claude Code 提示 API 密钥无效？ 密钥与 ANTHROPIC_BASE_URL 中的端点不匹配。网关 URL 需要网关密钥；Anthropic URL 需要控制台密钥。 ## 通过网关运行 Claude Code 相同的模型，两个环境变量，面值 7.69231 倍的额度，或固定费率不限量方案。 新账户：使用优惠码 FIXIT 可获得 $5 免费 API 额度。[获取 API 密钥](/register?promo=FIXIT) [查看不限量方案](/zh/plans/) AI Prime Tech 是独立的 API 网关，与 Anthropic 无关联，也未获得其认可或赞助。“Claude”和“Claude Code”是 Anthropic 的商标。此处介绍的 Claude Code 功能以撰写时 Anthropic 的公开文档为依据，且经常发生变化；本页面的价格和模型列表读取自此网关的实时设置。 ## 更多 Claude Code 指南 [Claude Code：完整指南](/claude-code/zh/)[如何安装 Claude Code](/claude-code/zh/install/)[Claude Code CLI 文档：命令与参数](/zh/claude-code/cli/)[Claude Code 定价与限制详解](/claude-code/zh/pricing/)[Claude Code SDK，现已更名为 Claude Agent SDK](/zh/claude-code/sdk/)[Claude Code 技能与插件](/zh/claude-code/skills/)[在 GitHub 中使用 Claude Code：App、Action 和 @claude](/zh/claude-code/github/)[Claude Code 有网页界面吗？网页、桌面与 IDE 版本详解](/zh/claude-code/web-and-desktop/)[Claude Code 使用哪个模型，以及如何更改](/zh/claude-code/models/)[Claude Code 开源吗？](/zh/claude-code/open-source/)[Claude Code 教程：您的首次实际会话](/claude-code/zh/tutorial/)[学生使用 Claude：Claude Code、API，以及教育优惠实际提供什么](/zh/claude-code/for-students/)[如何使用 Claude Code 实现 QA 自动化](/zh/claude-code/qa-automation/)[Claude Code 与 Cursor 对比：如何选择、何时使用，以及如何同时使用两者](/zh/claude-code/vs-cursor/)[Claude Code、Codex 与 OpenCode：终端智能体对比](/zh/claude-code/vs-codex/)[Claude Code 子智能体：工作原理、定义方法与智能体团队](/zh/claude-code/subagents/)[Claude Code 钩子：以确定性方式控制智能体的行为](/zh/claude-code/hooks/)[Claude Code MCP：连接服务器、作用域、远程 MCP 与实际示例](/zh/claude-code/mcp/)[Claude Code 生态系统：路由器、框架、插件及收录它们的清单](/zh/claude-code/ecosystem/)[在 VS Code 中使用 Claude Code：扩展、终端方式与常见错误](/zh/claude-code/vscode/)[如何在 Claude Code 中使用 OpenRouter（以及何时不宜使用）](/zh/claude-code/openrouter/)[Claude 速率限制错误：“API error: rate limit reached”的含义与解决方法](/zh/claude-code/rate-limits/)[Claude Code 怎么用：从安装到日常使用](/claude-code/zh/)