Claude Code 자주 발생하는 오류와 해결 방법

오류 메시지 색인

아래 오류 메시지는 Claude Code 2.1.299에서 테스트했습니다.

400

API Error: 400 {"error":"模型 xxx 不存在或未上线，请前往 https://aicodewith.com/zh/dashboard/pricing 查看可用模型列表 (request_id: …)"}

• •모델 이름의 철자가 틀렸거나 모델을 사용할 수 없습니다. /model을 실행해 다시 선택하거나 모델 페이지에서 모델 ID를 확인하세요.
• •컨텍스트가 너무 깁니다. /compact를 실행해 대화를 압축하거나 /clear로 새 세션을 시작하세요.

401 인증

Failed to authenticate. API Error: 401 {"error":"请在请求中提供有效的 API Key。"}

1. 대시보드에서 키를 다시 복사하고 앞뒤 공백과 줄바꿈이 없는지, 키가 삭제되지 않았는지 확인하세요.
2. 키를 ANTHROPIC_AUTH_TOKEN에 넣고 ANTHROPIC_API_KEY는 비워 두세요.
3. 새 터미널에서 echo $ANTHROPIC_API_KEY를 실행하고 ~/.zshrc 또는 ~/.bashrc에 있는 이전 값을 제거하세요.
4. 모든 Claude Code 세션을 닫고 다시 연 뒤 /status를 실행하세요.

403 키 비활성화

Failed to authenticate. API Error: 403 此 API Key 已被停用，如有疑问请联系我们 https://aicodewith.com/zh/contact

키가 비활성화되거나 삭제되면 이 오류가 몇 초 안에 나타납니다. 대시보드에서 키 상태를 확인하고 새 키를 만든 뒤 구성을 업데이트하세요. 문의 사항이 있으면 연락 주세요.

Not logged in

Not logged in · Please run /login

키가 비어 있거나 구성되지 않았다는 뜻입니다. Claude 계정에 로그인해야 한다는 의미가 아닙니다. ~/.claude/settings.json의 ANTHROPIC_AUTH_TOKEN에 키를 입력하고 Claude Code를 다시 시작하세요.

429 요청 제한

{"error":"当前并发请求过多，请稍后重试 (request_id: …)"}

(이 오류는 동시 curl 요청으로 재현했습니다. Claude Code 내부 표시는 다를 수 있습니다.)

종량제 API에는 5시간 또는 주간 할당량이 없지만 속도 및 동시성 제한은 적용됩니다. 한 번에 너무 많은 요청을 보내면 초과된 요청이 429를 반환합니다. 잠시 기다린 뒤 다시 시도하세요.

• •추가 Claude Code 세션을 닫고 병렬 서브에이전트를 줄이세요. 같은 키를 공유하는 스크립트와 CI 작업도 포함됩니다.
• •사용자 또는 파이프라인별로 별도 키를 만들어 출처를 더 쉽게 파악하세요.

overloaded

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

요청과 키는 정상이며, 해당 순간에 모델이 사용 중일 뿐입니다. 급증은 보통 짧고 특정 모델에만 영향을 줍니다.

• •잠시 기다린 뒤 다시 보내세요. 대화는 유실되지 않습니다.
• •/model을 실행해 다른 모델로 전환하세요(예: Opus에서 Sonnet으로). 먼저 작업을 처리할 수 있습니다.
• •모델 페이지에서 채널 상태를 확인하고 필요한 경우 키를 다른 채널로 전환하세요.

시간 초과 / 연결 끊김 (ECONNRESET)

API Error: Connection dropped (ECONNRESET)

API 엔드포인트에 연결할 수 없거나 도메인이 잘못되었을 때 이 오류가 나타납니다.

• •/status를 실행해 API 엔드포인트가 기본 Anthropic 주소가 아니라 api.aicodewith.ai인지 확인하세요.
• •로컬 프록시 또는 VPN을 잠시 끄고 다시 시도하세요. 중국에서의 연결은 직접 작동할 수 있습니다.

키가 잘못되었거나 네트워크에 연결할 수 없으면 Claude Code가 약 3–4분 동안 자동으로 재시도하며, 그동안 인터페이스는 아무 메시지 없이 비어 있습니다. 오래 멈춰 있으면 키와 엔드포인트를 먼저 확인하세요.

서드파티 API 문제 (Base URL, 구성 미적용)

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

ANTHROPIC_BASE_URL이 https://aicodewith.ai로 설정되어 있거나 잘못된 경로(예: /foo)가 있으면 이 오류가 발생합니다. 모델 문제처럼 보이지만 실제로는 엔드포인트가 잘못된 것이므로 https://api.aicodewith.ai를 사용하세요.

환경 변수는 ~/.claude/settings.json보다 우선합니다. 터미널에서 export한 이전 값이 구성 파일을 덮어씁니다. 구성을 변경한 뒤에는 모든 Claude Code 세션(VS Code 및 JetBrains 플러그인 포함)을 닫고 다시 여세요. 표준 구성은 다음과 같습니다.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的_API_KEY",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai"
  }
}

• •ANTHROPIC_BASE_URL에는 /v1이나 끝의 슬래시를 포함하지 마세요.
• •첫 실행이 로그인 페이지에서 멈추면 ~/.claude.json에 "hasCompletedOnboarding": true를 추가하세요.

Claude Code 연동 가이드Claude Code 中转 설정Claude Haiku API 오류 문제 해결

FAQ