Claude Code 常见错误与解决方案

使用 Claude Code 时难免会遇到各种错误。本文整理了最常见的错误类型及其解决方案，帮你快速排查和修复问题。

连接错误

ECONNREFUSED / ECONNRESET

无法连接到 API 服务器：

Error: connect ECONNREFUSED 104.18.x.x:443
Error: read ECONNRESET

原因：网络无法访问 Anthropic API 服务器，常见于国内网络环境。

解决方案：

• 使用 API 中转站，将 Base URL 指向可访问的地址
• 检查防火墙或代理设置是否拦截了请求
• 尝试 ping 目标域名确认网络连通性

# 使用中转站解决连接问题
export ANTHROPIC_BASE_URL="https://claude4u.com/antigravity"
export ANTHROPIC_AUTH_TOKEN="your-relay-key"

ETIMEDOUT / Timeout

Error: connect ETIMEDOUT
Error: Request timed out after 60000ms

原因：请求超时，可能是网络慢或服务器负载高。

解决方案：

• 检查网络速度和稳定性
• 如果使用官方 API，切换到中转站可降低延迟
• 减少请求中的 Token 数量（缩短 Prompt 或上下文）

认证错误

401 Unauthorized

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

原因：API Key 无效或过期。

解决方案：

1. 确认 API Key 正确，没有多余空格或换行
2. Claude Code 使用 ANTHROPIC_AUTH_TOKEN（不是 ANTHROPIC_API_KEY）
3. 检查 Key 是否已被撤销或过期
4. 确认 Base URL 和 Key 来自同一平台

403 Forbidden

Error: 403 {"error":{"type":"forbidden","message":"Your account does not have access"}}

原因：账户没有权限访问该模型或功能。

解决方案：

• 确认账户已完成验证和充值
• 部分模型（如 Opus）可能需要额外的访问权限
• 使用中转站时，确认中转站支持你请求的模型

模型错误

404 Model Not Found

Error: 404 {"error":{"type":"not_found_error","message":"model: claude-xxx not found"}}

原因：模型名称错误或该模型已下线。

解决方案：

• 检查模型名拼写，使用完整模型 ID
• 当前可用模型：
  • claude-opus-4-20250514
  • claude-sonnet-4-20250514
  • claude-haiku-3-5-20241022
• 旧模型名（如 claude-3-opus-20240229）可能已不可用

529 Overloaded

Error: 529 {"error":{"type":"overloaded_error","message":"Overloaded"}}

原因：Anthropic 服务器过载，暂时无法处理请求。

解决方案：

• 等待几秒后重试
• 使用中转站：好的中转站有多账户池和自动重试机制，能自动规避过载账户
• 避开高峰时段（通常美国工作时间负载最高）

请求错误

400 Bad Request

Error: 400 {"error":{"type":"invalid_request_error","message":"..."}}

常见原因和解决方案：

• Token 超限：输入超过模型的上下文窗口，使用 /compact 压缩上下文
• 格式错误：消息格式不符合 API 规范，检查 JSON 结构
• 参数无效：max_tokens 等参数超出允许范围

429 Rate Limited

Error: 429 {"error":{"type":"rate_limit_error","message":"Rate limit exceeded"}}

原因：请求频率超过账户限制。

解决方案：

• 降低请求频率，添加请求间隔
• 使用中转站的多账户池提升总体限额
• 升级 Anthropic 账户的用量层级（需要消费到一定金额）

Claude Code 特有问题

权限被拒绝

Claude Code 尝试执行文件操作或命令但被拒绝。

解决方案：在 ~/.claude/settings.json 中预先授权常用命令：

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git *)"
    ]
  }
}

上下文过长导致性能下降

长时间会话后 Claude Code 变慢或回复质量下降。

解决方案：

• 使用 /compact 压缩上下文
• 使用 /clear 清空并开始新会话
• 将大任务拆分成多个小的独立会话