Claude Code 오류와 해결 방법

오류별 상세 가이드

• API 오류: 500(내부 서버 오류) — 서비스 중단, 모델별 장애, 0%에서의 컨텍스트 압축.
• 과부하 / API 오류 529 — 처리 용량, 재시도, 하위 에이전트 요청 급증.
• API 오류 400 — 너무 긴 프롬프트, 도구 사용 동시 실행, 기타 거부된 요청.
• OAuth 오류 — 15000ms 제한 시간 초과, 로그인 시 상태 코드 500.
• 프로세스 종료 코드 1 — VS Code 확장 프로그램 및 데스크톱 앱 충돌.
• 요청 제한 도달 / 429 — 세 가지 한도와 이를 높이는 방법.
• 너무 긴 프롬프트 / 컨텍스트 한도 도달 — 컨텍스트 창을 채우는 요소, 잘못된 경고, 압축 실패, claude.ai 길이 제한.
• 사용 한도 도달 — 세션, 주간 및 Opus 사용 기간, "지정된 API 사용 한도", "크레딧 잔액이 너무 적음".
• 401 / 403 인증 — 유효하지 않은 자격 증명, 유효하지 않은 API 키, "로그인되지 않음", host_not_allowed.
• 연결 오류 — ECONNRESET, "API 응답 대기 중", 인증서, 프록시, 재시도 변수.
• 멈춤, 진행 중단, 응답 없음 — 멈춘 지점, 탈출 키, 알려진 멈춤 버그, 메모리.
• claude.ai 작동하지 않음 — "문제가 발생했습니다", 처리 용량 제약, 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 — 요청 제한 / 요청률 초과

분당 요청 수, 분당 토큰 수, 동시 요청 수라는 세 가지 한도가 적용됩니다. 에이전트 세션은 동시 요청 한도에 먼저 도달합니다. 각 하위 에이전트가 완료될 때까지 슬롯을 점유하는 병렬 스트리밍 요청이기 때문입니다. 병렬 실행 수를 줄이고 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 직접 실행하세요. 실제 메시지를 확인할 수 있으며, 원인은 거의 항상 18 미만의 Node.js 버전, npm 설치 후 손상된 PATH, 손상된 네이티브 설치, 또는 유효하지 않은 JSON이 포함된 settings.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 페이지.

"정상적인 업스트림 없음"

API 오류가 아닙니다. 서비스 앞단의 로드 밸런서가 사용 가능한 백엔드가 없다고 보고하는 메시지입니다. 공식 엔드포인트에서는 서비스 중단을 뜻하고, 게이트웨이에서는 전체 업스트림 풀이 중단되었거나 제한을 받고 있다는 뜻입니다. 기다린 뒤 재시도하세요. 설정은 변경하지 마세요.

Claude Code가 전혀 작동하지 않음

• 시작한 뒤 아무 메시지 없이 종료됨 → 다음 명령 실행: claude /doctor; 보통 Node 버전 또는 PATH 문제입니다.
• 시작 시 또는 세션 도중 멈춤 → 다음 참조: 멈춤 및 진행이 중단된 세션 및 연결 오류.
• command not found → 설치 가이드를 참조하세요.
• 권한 오류로 도구 실행 실패 → /permissions, 또는 --allowedTools 를 스크립트에서 사용하세요.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

자주 묻는 질문

AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.