Claude Code의 API Error 401/500은 내 잘못인가 Anthropic 측의 문제인가 — 구분 및 대처 (#69706)

Claude Code에서 갑자기 API Error: 401 Invalid authentication credentials나 API Error: 500 Internal server error가 발생하면, 우선 "내 설정이 망가진 것인지, Anthropic 측의 장애인지"를 알 수 없습니다. 이 부분을 혼동하면 고쳐지지 않는 조작(logout → login → 재설치)을 몇 번이고 반복하며 시간을 허비하게 됩니다. 실제로 이슈 #69706의 20개 댓글을 읽어보면, 성질이 다른 두 종류의 401 에러가 하나의 스레드에 섞여 있어서, 한쪽의 해결 방법을 다른 쪽에 적용하느라 "무엇을 해도 고쳐지지 않는다"고 하는 사람들이 있습니다.

이 기사는 에러 본문과 이슈 보고를 바탕으로 한 구분 방법입니다. 에러 문구 자체와 ~/.claude/.credentials.json의 구조는 필자의 환경에서 확인한 사실로서 기술하며, 각 이용자의 환경에서 무엇이 일어났는지는 이슈 보고에 기반한 전언으로서 구분하여 작성합니다.

401과 500은 원인이 발생하는 위치가 완전히 다릅니다. 같은 "API 에러"라도 해야 할 일이 정반대입니다.

에러	원인 위치	직접 고칠 수 있는가
500 / 503 / 타임아웃 (Timeout) / 응답 없음	거의 Anthropic 서버 측	고칠 수 없음 (기다림·재시도)
401 Invalid authentication credentials	클라이언트 측 또는 계정 측	상황에 따라 다름 (후술에서 이분)

500 Internal server error는 에러 본문 안에 이미 답이 적혀 있습니다.

API Error: 500 Internal server error. This is a server-side issue,
usually temporary — try again in a moment.
If it persists, check https://status.claude.com.

This is a server-side issue (이것은 서버 측의 문제입니다)라고 명시되어 있습니다. 503 Service Unavailable이나 응답이 돌아오지 않는 타임아웃도 같은 계통입니다. 이것들은 당신의 설정으로는 고칠 수 없습니다. 해야 할 일은 세 가지뿐입니다.

• status.claude.com 을 확인한다. 장애가 발생했다면 확실히 기다려야 한다.
• 잠시 기다린 후 한 번만 시도한다. 500 에러는 대개 일시적이다.
• 그래도 계속된다면, 같은 명령어를 연타하지 마라. 간격을 두고 재시도한다 (지수 백오프 (Exponential Backoff) = 1초, 2초, 4초...와 같이 대기 시간을 배로 늘려간다).

여기서 중요한 것은 같은 조작을 즉시 반복하지 않는 것입니다. 서버 측이 일시적으로 막혀 있는 상태일 때, 쉬지 않고 연타하면 복구를 기다리는 것보다 더 늦어집니다. 500 에러를 보면 설정을 건드리기 전에 먼저 status를 확인한다. 이것만으로도 고칠 수 없는 것을 고치려는 낭비를 없앨 수 있습니다.

여기가 본론입니다. 401 Invalid authentication credentials에는 겉보기에는 같아 보여도 원인이 다른 두 가지 유형이 있으며, 해결 방법이 다릅니다. #69706에서 "logout도 login도 재설치도 통하지 않는다"며 막혀 있는 사람들의 대부분은, 자신이 어느 유형인지 확인하지 않은 채 다른 유형의 해결 방법을 적용하고 있습니다.

Claude Code는 인증 토큰을 ~/.claude/.credentials.json (Windows는 자격 증명 저장소)에 저장합니다. 이 안의 refreshToken이 빈 문자열이 되어 있으면 401 에러가 발생합니다. 이슈 보고에 따르면, 어떤 이용자가 이 파일을 열어 refreshToken이 비어 있는 것을 발견했고, 다른 정상 작동하는 머신에서 유효한 refreshToken을 복사해 오니 작동했다고 보고했습니다.

확인 방법 (읽기만 하세요. 내용은 비밀이므로 화면 공유나 붙여넣기는 하지 마십시오):

# refreshToken 이 빈 문자열이 아닌지만 확인
cat ~/.claude/.credentials.json | grep -o '"refreshToken":"[^"]*"' | head -c 30

"refreshToken":""와 같이 값이 비어 있다면, 이것이 유형 1입니다. 해결 방법:

• 환경 변수를 의심한다.
  echo $ANTHROPIC_API_KEY

값이 비어 있는지 확인합니다. 구독(OAuth) 용도로 사용하려는데, 무효하거나 다른 용도의 값이 들어 있을 수 있습니다. 구독 용도로 사용하려면, 이 환경 변수를 해제한 후 다시 login 합니다. ANTHROPIC_API_KEY나 apiKeyHelper가 설정되어 있으면 해당 값이 우선되어 401 에러가 발생합니다. 그래도 해결되지 않는다면, ~/.claude/.credentials.json을 일단 삭제하고 claude login으로 새로 다시 로그인합니다.

여기까지가 "사용자 측에서 직접 해결할 수 있는" 범위입니다.

반면, 이슈 제기(ticket) 내용 중에는 사용자의 조작만으로는 전혀 해결되지 않는 유형들이 나열되어 있습니다. 이들은 자격 증명(credentials) 파일의 문제가 아니므로, 유형 1의 해결 방법(파일 삭제, 재로그인, 재설치)을 적용해도 고쳐지지 않습니다. 다음 중 하나에 해당한다면 유형 2입니다.

• logout → login → ~/.claude/.credentials.json 삭제 → 재설치 → 새로운 setup-token 발행까지 전부 수행해도 401 에러가 사라지지 않음 (48시간 동안 지속된다는 보고 있음).
• 구독 계정으로 login 하려고 하면, 이미 Max 플랜임에도 불구하고 "Max로 업그레이드하세요"라는 결제 페이지로 이동함. 플랜을 선택하면 결제 화면으로 넘어가며, 루프(loop)에서 빠져나올 수 없음.
• 하나의 계정을 여러 명이 공유하고 있는데, 모두가 동시에 연결이 끊김 (계정의 동시 이용이 제한되었을 가능성. 이는 사용자 설정으로 되돌릴 수 없습니다).
• 모바일 세션은 살아있고 히스토리도 무사한데, 다른 경로를 통한 신규 로그인만 실패함.

유형 2는 Anthropic 측의 계정 상태나 로그인 인프라의 문제입니다. 해야 할 일은 사용자 측 설정을 계속 만지는 것이 아니라, 고객 지원(support)에 티켓을 접수하는 것입니다. #69706에서는 여러 사람이 지원 티켓을 제출하고 답변을 기다리고 있습니다. 고쳐지지 않는 조작을 반복하기보다, 유형 2임을 확인하고 기다리는 것이 결과적으로 더 빠르게 문제를 해결하는 길입니다.

logout / login을 반복하기 전에, 딱 한 번만 이 단계를 수행하십시오. 어느 유형인지 여기서 거의 결정됩니다.

ls -l ~/.claude/.credentials.json
cat ~/.claude/.credentials.json | grep -o '"refreshToken":"[^"]*"' | head -c 30

• refreshToken이 비어 있거나, 환경 변수에 불필요한 ANTHROPIC_API_KEY가 들어 있는 경우 → 유형 1. 직접 해결 가능 (파일 삭제 + 재로그인, 환경 변수 해제).
• 파일은 정상으로 보이지만, 새로운 토큰을 다시 받아도 거부되거나 결제 페이지 루프에 빠지는 경우 → 유형 2. 고객 지원 대상. 사용자 측 조작을 멈추고 티켓을 제출하십시오.

이 순서가 중요합니다. 많은 사람이 막히는 이유는 유형을 확인하기 전에 유형 1의 조작을 반복하기 때문입니다. 500 에러를 보면 status를 확인하고, 401 에러를 보면 먼저 자격 증명 파일을 확인하십시오. 원인이 있는 위치를 먼저 특정하면, 고칠 수 없는 것을 고치려고 허비하는 시간을 줄일 수 있습니다.

이 글은 응급 분류에 집중했지만, 돈과 관련된 이차 피해에 대해 한 가지만 적어두겠습니다. 401 에러로 차단되고 고객 지원 답변도 오지 않으면, 사람들은 "어떻게든 작동시키고 싶다"는 일념으로 로그인 옵션 중 "API 키로 사용하기"를 선택하기 쉽습니다. 데스크톱 버전이 그렇게 권장하는 경우도 있습니다.

하지만 이것은 인증의 수리가 아닙니다. API 키 경로는 구독 범위와는 별개로, 토큰 사용량에 따른 종량제(pay-as-you-go) 경로입니다. 구독의 401 에러를 피하려고 이 옵션을 선택하면, 이후의 작업은 실비로 과금되며, 심지어 "현재 종량제로 과금되고 있다"는 강력한 경고 없이 비용이 쌓이게 됩니다. #69706 스레드에도 바로 이 방식으로 실비를 낭비했다는 보고가 있습니다. 구독이 살아있다면 고쳐야 할 것은 인증이지, 결제 경로를 바꾸는 것이 아닙니다.

이 "처음 발생한 고장보다 당황해서 취한 다음 조치가 회수 불가능한 손해로 이어지는" 이차 피해와, logout으로 완전히 지워지지 않는 OS의 키체인(Keychain) / 자격 증명 관리자(Credential Manager) 정리, 화면이 없는 환경(Codespaces, SSH 접속 환경, Chromebook)에서 localhost 리다이렉션이 전달되지 않아 새로운 토큰조차 받을 수 없는 유형과 setup-token...

이러한 탈출구까지 한 단계 더 깊게 정리한 것이 바로 Claude Code 사고 방지 핸드북(Claude Code 事故防止ハンドブック, ¥800・제3장까지 무료)의 제55장입니다. 이 기사의 응급 처치만으로 충분했다면, 거기까지만 보셔도 충분할 것입니다. 더 깊은 탐구가 필요할 때를 위한 참조처로 남겨둡니다. 또한, 구독(Subscription) 위에 API 키(ANTHROPIC_API_KEY나 apiKeyHelper)가 얹혀져 종량제(Pay-as-you-go)로 전환되어 있는 상태를 세션 시작 시에 경고하는 무료 hook은 cc-safe-setup (MIT)에 포함되어 있습니다.

이 기사는 이슈(Issue) #69706과 그 안에서 보고된 500 에러의 본문을 바탕으로 작성되었습니다. 에러 문구와 ~/.claude/.credentials.json의 구조는 필자가 확인한 사실이며, 각 사용자의 환경에서 어떤 일이 일어났는지(빈 refreshToken, 과금 루프, 공유 계정의 동시 접속 끊김 등)는 이슈 보고에 기반한 전언입니다. Anthropic 측의 서버 및 계정 상태는 필자로부터 관측할 수 없습니다. 어려움을 겪는 분들에게 도움이 되기를 바라는 마음으로, 혼재되어 있던 두 가지 유형의 401 에러를 구분해 보았습니다.