클로드 코드 오류 정리 — 401·429·529와 설치 오류 구분법

클로드 코드 오류는 크게 두 종류이고, 검색 결과 대부분은 그중 한쪽만 다룹니다. 설치·실행 단계의 클라이언트 오류와, 모델을 호출할 때 돌아오는 API 오류는 원인도 해결 방법도 완전히 다릅니다. 이 글은 두 번째 — 401, 429, 529 — 를 중심으로 정리합니다. 구독에서 API 키로 옮기는 순간 가장 먼저 마주치는 오류들이기 때문입니다.

오류 문자열은 어느 나라에서든 영어로 나옵니다. 아래에서는 문자열을 원문 그대로 두고 설명만 한국어로 씁니다.

먼저 30초 만에 원인을 세 갈래로 나누기

설정을 바꿔보기 전에 엔드포인트에 직접 한 번 요청을 보내세요. 이 한 번이 “클라이언트 문제 / 인증 문제 / 서버 문제”를 갈라 줍니다.

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401 — 키가 아니라 헤더가 틀린 경우

키를 몇 번씩 새로 발급받아도 401이 계속 난다면 값이 아니라 보내는 방식을 의심하세요. Claude Code는 ANTHROPIC_AUTH_TOKEN을 Authorization: Bearer 헤더로 보내고, ANTHROPIC_API_KEY는 x-api-key 헤더로 보냅니다. 게이트웨이는 대부분 앞쪽을 기대하므로, 두 변수를 바꿔 넣으면 멀쩡한 키로도 401이 납니다.

두 변수가 동시에 남아 있는 경우도 흔합니다. 하나를 지우고 셸을 새로 연 뒤 다시 시도하세요. 변수별 차이는 ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY의 차이에 정리돼 있습니다.

429 — 두 가지 서로 다른 429

같은 숫자지만 원인이 완전히 다릅니다. 구독으로 쓰는 중이라면 세션 창 한도에 걸린 것이고, 창이 초기화될 때까지 기다리는 것 외에 방법이 없습니다 — 상위 요금제로 올리는 것도 그 순간에는 도움이 되지 않습니다. API 키로 쓰는 중이라면 초당 요청 수나 토큰 처리량 제한이며, 지수 백오프 재시도로 대부분 해결됩니다.

어느 쪽인지는 ANTHROPIC_BASE_URL이 설정돼 있는지로 바로 구분됩니다. 설정돼 있으면 구독이 아니라 키를 쓰는 중입니다. 구독 한도의 구조와 초과했을 때의 선택지는 클로드 코드 요금에서 다룹니다.

529 overloaded_error — 내 문제가 아닌 오류

529는 업스트림 모델 서버가 일시적으로 과부하라는 뜻입니다. 요청 내용도, 키도, 잔액도 원인이 아니므로 설정을 고쳐서 없앨 수 있는 오류가 아닙니다. 대응은 재시도뿐이고, 즉시 재시도보다 지수 백오프가 성공률이 훨씬 높습니다.

자동 폴백이 있는 게이트웨이를 거치면 한 업스트림이 529를 낼 때 요청이 다른 경로로 넘어가므로 체감 빈도가 줄어듭니다. 영어권 독자를 위한 상세 정리는 529 overloaded_error 대응에 있습니다.

구독 한도에 걸렸을 때 이어서 작업하기

429가 구독 쪽이라면 기다리는 대신 그 세션만 키로 넘길 수 있습니다. 구독을 해지할 필요는 없습니다 — 아래 두 변수가 설정돼 있는 동안에만 키로 청구되고, 지우면 원래대로 돌아옵니다.

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# 백그라운드 작업을 가장 싼 모델로 보내는 한 줄 — 매 세션 효과가 있습니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

요율은 카탈로그에서 그대로 읽어옵니다: Claude Sonnet 4.6은 1M 토큰당 $1.20 / $6.00, Claude Haiku 4.5은 $0.40 / $2.00. 선불 잔액에서 차감되므로 작업하지 않은 달에는 비용이 발생하지 않습니다. 결제 수단과 국내 카드 등록 방법은 Claude API 가격·결제에 정리돼 있습니다.

설치 단계 오류는 별개입니다

설치가 안 되는 문제는 Node.js 버전이나 전역 설치 권한이 원인인 경우가 대부분이며, 위의 세 오류와는 계통이 다릅니다. 먼저 claude --version이 정상적으로 출력되는지 확인하세요. 출력되면 설치는 끝난 것이고, 그 뒤의 문제는 인증이나 네트워크 쪽입니다. 두 계통을 섞어서 접근하면 시간이 가장 많이 듭니다.

FAQ