클로드 코드 오류 해결: 529·Prompt is too long·로그인 오류 뜰 때 할 일

이 글 순서

1. 오류 문구가 뭔가요
2. 처음이라면: 세 가지
3. 서버 쪽 오류
4. 로그인 오류
5. 한도·돈 관련 오류
6. 익숙해졌다면: 대화가 꽉 찰 때
7. 더 깊이: 연결 오류
8. 오류 없이 이상할 때
9. 알리기: /feedback
10. 코덱스·안티그래비티는
11. 오류별 먼저 할 일
12. 한국에서 되나
13. 다음에 볼 글
14. 참고한 자료

클로드 코드를 켜 두고 일을 맡겼는데 빨간 영어 한 줄이 뜨고 멈추면 당황스러워요. “내가 뭘 잘못 눌렀나”, “계정이 막혔나” 싶어 이것저것 건드리기 쉬운데, 대부분은 문구만 제대로 읽으면 할 일이 정해져 있어요. 이 글은 오류 문구가 처음인 분을 기준으로, 자주 만나는 문구를 종류별로 나누고 각각 무엇을 하면 되는지 적었어요.

클로드 코드 공식 문서의 오류 참조(Error reference), 문제 해결(Troubleshooting), 설치 및 로그인 문제 해결 쪽을 2026년 10월 9일에 영어·한국어로 읽고 옮겼어요. 캡처는 한국어 문서에서 했고 내용은 영어 문서와 맞춰 봤어요. 터미널 그림은 클로드 코드 2.1.295 를 실제 설정과 떼어 둔 테스트 폴더에 받아, 윈도우 PC 에서 같은 날 로그인 없이 돌린 출력이에요. 로그인해야 나오는 오류(529, 한도, 429 등)는 직접 띄우지 않고 문서에 적힌 대로 옮겼어요.

오류 문구가 뭔가요

단어부터 풀게요. 클로드 코드는 터미널(마우스 대신 글자로 컴퓨터에 일을 시키는 까만 창)에서 돌아가는 Anthropic 의 AI 도구예요. 내 컴퓨터에 깔린 프로그램이지만, 생각하고 답을 만드는 일은 인터넷 너머 Anthropic 서버의 모델(답을 만들어 내는 AI 본체)이 해요. 내 컴퓨터의 클로드 코드가 서버에 “이 요청에 답해 줘”라고 보내고 답을 받아 오는데, 이렇게 프로그램끼리 정해진 형식으로 주고받는 창구를 API 라고 불러요.

오류 문구는 이 주고받기 어딘가가 막혔을 때 클로드 코드가 띄우는 한 줄이에요. 식당으로 치면 주문서가 주방에 안 닿았는지(연결), 주방이 너무 바쁜지(서버), 손님 확인이 안 됐는지(로그인), 오늘 먹을 수 있는 양을 다 먹었는지(한도) 알려 주는 메시지예요. 그래서 문구를 보면 어느 쪽 문제인지 먼저 구분할 수 있어요.

문서는 이 오류들이 터미널의 클로드 코드뿐 아니라 데스크톱 앱의 코드 탭, 브라우저에서 여는 클라우드 세션에서도 똑같이 뜬다고 적었어요. 셋 다 속은 같은 클로드 코드라서예요. 다만 데스크톱 앱에서는 문구가 조금 다르게 나오는 것이 있어서, 아래에서 따로 짚을게요.

처음이라면: 세 가지

문구가 뜨면 이 순서만 기억해 두세요.

1. 문구를 끝까지 읽어요. 영어라도 숫자(500, 529, 429)와 앞 몇 단어가 중요해요. 화면을 캡처해 두거나 문구를 그대로 복사해 두면 찾을 때 편해요.
2. 잠깐 기다렸다 다시 보내요. 문서에 따르면 클로드 코드는 오류를 보여 주기 전에 이미 최대 10번까지 간격을 늘려 가며 다시 해 봐요. 그래도 뜬 거라면 몇 분 뒤에 다시 보내는 게 첫 수예요. 긴 요청을 다시 붙여 넣을 필요 없이 try again 이라고만 쳐도 된다고 적혀 있어요. 원래 요청이 대화에 남아 있어서예요.
3. 점검을 돌려요. 클로드 코드 안에서는 /doctor, 클로드 코드가 아예 안 켜지면 터미널에서 claude doctor 예요.

다시 하는 동안에는 일하는 표시 옆에 Retrying in Ns · attempt x/y 처럼 몇 초 뒤 몇 번째로 다시 하는지가 떠요. 20초 동안 아무 답이 안 오면 Waiting for API response 와 “네트워크를 확인하라”는 줄이 뜨는데, 문서는 이게 아직 실패가 아니라고 적었어요. 이 단계에서는 그냥 기다리면 돼요.

오류 찾기 표 쓰는 법

오류 참조 문서 맨 위에 “오류 찾기” 표가 있어요. 왼쪽 칸에 화면에 뜬 문구, 오른쪽 칸에 그 문구를 다룬 절이 있어요. 문서가 아주 길어서(문구가 수백 줄), 브라우저에서 Ctrl+F 를 눌러 문구 앞 몇 키워드로 검색하는 게 가장 빨라요. 자주 만나는 줄만 남겨 캡처했어요.

설치가 안 되거나(command not found), 설정 파일이 안 먹거나, 많이 느려지는 것처럼 “오류 한 줄”이 아닌 문제는 문제 해결 문서의 첫 표가 어느 문서로 가야 하는지 알려 줘요.

설치 단계의 오류는 클로드 코드 설치 윈도우 초보용 글의 “막혔을 때 볼 곳”에, 설정 파일 오류는 클로드 코드 settings.json 설정하는 법 글의 “막힐 때”에 따로 있어요. 이 글은 설치가 끝나고 쓰는 중에 뜨는 오류를 다뤄요.

claude doctor 돌리기

둘 다 점검이지만 쓰는 자리가 달라요. 클로드 코드 안에서 치는 /doctor 는 설치·설정·확장·컨텍스트 사용량을 보고, 고칠 수 있는 것은 내가 승인하면 고쳐 준다고 문서에 적혀 있어요. 터미널에서 치는 claude doctor 는 세션을 열지 않고 읽기만 하며 점검해요. 클로드 코드가 켜지지도 않을 때 쓰는 쪽이에요.

claude doctor

“클로드 코드의 설치와 설정 상태를 점검해서 알려 줘”예요. 테스트 폴더에서 돌린 출력이에요.

끝에 “No installation issues found”(설치 문제 없음)가 나오면 설치는 괜찮은 거예요. Auto-updates 줄의 disabled 는 테스트 폴더라 자동 업데이트를 일부러 꺼 둔 것이라, 평소 PC 에서는 다르게 나와요. 테스트 폴더는 로그인을 안 해서 회사 설정·Remote Control 쪽에 “로그인이 없다”는 줄이 같이 나왔는데, 이건 설치 문제가 아니에요. 설정 파일이 깨졌다면 Invalid settings 라는 항목이 따로 생겨요(설정 글에 그림이 있어요).

서버 쪽 오류

내가 잘못한 게 아니라 Anthropic 서버(또는 그 앞의 중간 서버)가 잠깐 탈이 난 경우예요. 대부분 기다리면 풀려요.

API Error: 500

화면에는 API Error: 500 Internal server error. This is a server-side issue, usually temporary 로 시작하는 줄이 떠요. 문서는 서버 안에서 생긴 뜻밖의 실패이고, 내 요청·설정·계정 탓이 아니라고 적었어요. 할 일은 셋이에요.

• status.claude.com 에서 지금 장애 공지가 있는지 봐요. 서비스 상태를 알려 주는 공식 페이지예요.
• 1분쯤 기다렸다가 try again 으로 다시 보내요.
• 공지도 없는데 계속 뜨면 /feedback 으로 알려요(아래 “알리기” 절).

회사망의 중간 서버가 막은 경우엔 API Error: 502 Bad Gateway 처럼 다른 숫자와 그 쪽 페이지 제목이 붙어 나온다고 해요. 500번대 숫자면 같은 종류로 보면 돼요.

529 Overloaded

가장 자주 보는 것 가운데 하나예요. API Error: Repeated 529 Overloaded errors. The API is at capacity 로 시작해요. 서버가 모든 사용자를 받느라 잠깐 꽉 찼다는 뜻이에요.

빨간 테두리 두 곳이 핵심이에요. 첫째, 529 는 내 사용 한도가 아니라서 이 오류로 한도가 깎이지 않아요. 둘째, 바쁜 정도는 모델마다 따로라서 /model 로 다른 모델로 바꾸면 바로 이어서 일할 수 있어요. 한 모델만 특히 바쁘면 클로드 코드가 먼저 Opus is experiencing high load, please use /model to switch to Sonnet 처럼 바꾸라고 알려 줘요. 데스크톱 앱에서는 “Switch to Sonnet.” 으로 나오고 앱의 모델 고르는 칸에서 바꿔요. 모델 바꾸는 법은 클로드 코드 모델 바꾸는 법 글에 있어요.

시간이 넘었을 때

Request timed out 은 서버가 정한 시간 안에 답하지 않았다는 뜻이에요. 기본으로 기다리는 시간은 10분이에요. 서버가 바쁘거나 아주 긴 답을 만들 때 생길 수 있으니 다시 보내 보고, 인터넷이 느린 곳이라면 아래 “재시도 손보기”의 API_TIMEOUT_MS 를 늘려요. API Error: No response from API 도 비슷한데, 답의 첫 조각조차 안 왔다는 뜻이라 반복되면 네트워크나 회사 프록시를 의심하라고 문서에 적혀 있어요.

답이 중간에 끊겼을 때

Claude 가 답을 쓰던 중에 연결이 끊기면 The response above may be incomplete.(위의 답이 덜 끝났을 수 있음)가 붙어요. 앞에는 끊긴 이유가 서버 오류인지, 연결이 끊겼는지, 컴퓨터가 잠자기에 들어갔는지 적혀 있어요.

이때 클로드 코드는 처음부터 다시 보내지 않아요. 다시 보내면 파일 고치기 같은 같은 일을 두 번 할 수 있어서, 끝낸 부분까지는 남겨 두고 이 알림을 붙여요. 그래서 할 일은 간단해요. 화면에 남은 답을 읽고 continue 라고 치면 마지막으로 끝낸 곳부터 이어서 해요. 노트북 덮개를 닫았다 열었을 때 이 문구를 자주 보게 될 거예요.

로그인 오류

클로드 코드가 “당신이 누구인지” 서버에 증명하지 못한 경우예요. 거의 모두 /login 한 번으로 풀려요.

• Not logged in · Please run /login: 이 세션에 쓸 로그인 정보가 없어요. /login 을 쳐서 구독 계정(claude.ai)이나 Console 계정으로 로그인해요. 데스크톱 앱에서는 Authentication required · Sign in again to continue 로 나오고 앱에서 다시 로그인해요.
• OAuth token revoked, OAuth token has expired: 저장해 둔 로그인이 더는 안 통해요. 모든 곳에서 로그아웃했거나 관리자가 권한을 거뒀거나, 자동으로 새로 받다가 실패한 경우예요. 역시 /login.
• Login expired · Please run /login: 로그인을 새로 받으려다 실패해서 클로드 코드가 저장된 로그인을 지운 상태예요. 이때는 서버에 묻지도 않고 바로 멈춰요. /login 만이 새 로그인을 만들어요.

로그인 없이 테스트 폴더에서 클로드 코드에 한 줄 물어보면 첫 줄이 그대로 나와요.

claude -p "hi"

“화면을 열지 말고 hi 에 대한 답만 출력해 줘”예요. -p 로 화면 없이 쓰는 법은 클로드 코드 claude -p 사용법 글에 있어요.

-p 로 돌린 스크립트에서 로그인이 만료되면 문구가 Failed to authenticate 로 시작한다고 해요. 문서는 같은 컴퓨터에서 claude 를 한 번 켜서 /login 을 마친 뒤 스크립트를 다시 돌리라고 적었어요. 매번 로그인할 수 없는 자동화라면 API 키나 claude setup-token 으로 만든 오래 가는 토큰을 쓰라고 해요.

로그인이 몇 번을 해도 계속 풀리거나, 로그인 창에서 막힌다면 설치 글의 로그인 부분으로 가요. 문서가 권하는 순서는 /logout, 창 닫기, 다시 켜서 처음부터 로그인이에요.

한도·돈 관련 오류

이 종류는 문구가 비슷해 보여도 뜻이 꽤 달라서, 하나씩 떼어 볼게요.

문구 앞부분	뜻	할 일
You’ve hit your session limit	5시간 한도를 다 씀	적힌 시각까지 기다림
You’ve hit your weekly limit	주간 한도를 다 씀	적힌 요일·시각까지
You’ve hit your Opus limit	그 모델 묶음 한도만	/model 로 다른 묶음
Server is temporarily limiting requests	서버가 잠깐 조임, 내 한도 아님	잠깐 뒤 다시
Request rejected (429)	API 키 쪽 속도 제한	/status 로 키 확인
Credit balance is too low	Console 선불 잔액 없음	/status 로 키 확인

출처: 클로드 코드 오류 참조 문서의 사용 한도 절. 10월 9일 확인.

5시간·주간 한도는 모든 모델이 같이 쓰는 몫이라 모델을 바꿔도 안 풀려요. 남은 양 보는 곳과 초기화되는 시각, 한도가 풀리면 알아서 이어 하게 하는 설정은 클로드 코드 사용량 확인하는 법 글에 자세히 있어요. Pro·Max 는 /usage-credits 로 추가 사용분을 살 수 있고, Team·Enterprise 는 같은 명령이 관리자에게 요청을 보낸다고 문서에 적혀 있어요.

구독인데 429·잔액 부족

초심자가 가장 헷갈리는 자리예요. Pro·Max 구독으로 쓰는데 Request rejected (429) 나 Credit balance is too low 가 뜬다면, 구독이 아니라 API 키로 돈을 내는 방식으로 빠졌을 수 있어요. API 키는 Console(개발자용 결제 화면)에서 만든 긴 비밀 문자열로, 쓴 만큼 돈이 나가는 키예요. 예전에 시험 삼아 넣어 둔 ANTHROPIC_API_KEY 환경 변수(컴퓨터가 기억해 두는 이름이 붙은 값)가 남아 있으면, 승인해 둔 그 키가 구독 로그인보다 먼저 쓰여요.

먼저 클로드 코드 안에서 /status 를 쳐서 API key 줄이 있는지 봐요. 있다면 PowerShell(윈도우에 들어 있는 터미널)에서 지금 창에 그 값이 걸려 있는지 이렇게 봐요.

Get-ChildItem Env: | Where-Object Name -like 'ANTHROPIC*'

“이름이 ANTHROPIC 으로 시작하는 환경 변수를 모두 보여 줘”예요. 테스트 폴더처럼 아무것도 안 나오면 걸린 게 없는 거예요. ANTHROPIC_API_KEY 가 보이고 구독으로 쓰고 싶다면 이 줄로 지금 창에서 지워요.

Remove-Item Env:ANTHROPIC_API_KEY

“이 창에서 ANTHROPIC_API_KEY 를 지워 줘”예요. 이 창에서만 지워지는 거라, 윈도우 설정(시스템 속성의 환경 변수 창)이나 PowerShell 프로필 파일에 적어 둔 것이면 거기서도 지우고 새 창에서 claude 를 켜요. 아직 구독으로 로그인하지 않았다면 /login 까지. 반대로 정말 API 키로 쓰는 중이라면 platform.claude.com 의 결제 화면에서 잔액을 채우는 게 맞아요. Max 요금제에 매달 붙는 API 크레딧이 대화형 클로드 코드에는 안 쓰인다는 점은 클로드 API 크레딧 받는 법 글에 있어요.

같은 이유로 API Error: 401 Invalid authentication credentials 가 뜰 수도 있어요. 문서는 이것도 /status 로 지금 쓰는 인증 방식이 로그인인지 API 키인지 먼저 보고, API 키면 위처럼 지우거나 Console 에서 새 키로 바꾸고, 로그인이면 /login 을 한 번 하라고 적었어요.

익숙해졌다면: 대화가 꽉 찰 때

한 대화를 오래 이어 가거나 큰 파일을 통째로 붙여 넣으면 Context limit reached · /compact or /clear to continue 가 떠요. 화면 없이 -p 로 돌렸다면 Prompt is too long 으로 나와요. 컨텍스트는 모델이 한 번에 읽을 수 있는 대화의 양이에요. 책상 위에 펼쳐 둘 수 있는 종이 양이 정해져 있다고 보면 돼요.

• /compact: 앞의 대화를 요약해서 자리를 비워요. 하던 일을 이어 갈 때.
• /clear: 대화를 비우고 새로 시작해요. 앞 일과 상관없는 새 일일 때.
• /context: 무엇이 자리를 차지하는지 나눠 보여 줘요. 시스템 안내, 도구, 메모리 파일(CLAUDE.md), 대화 순이에요.
• /mcp disable 이름: 안 쓰는 MCP 서버(바깥 도구를 연결하는 통로)를 꺼서 그 도구 설명이 차지하던 자리를 비워요.

/compact 가 Not enough messages to compact. 로 답하면, 요약할 앞 대화가 없을 만큼 요청 하나가 너무 큰 거예요. /clear 하고 붙여 넣을 글이나 파일을 줄여 다시 보내요. 자동 압축은 기본으로 켜져 있어서 보통은 이 오류를 막아 주는데, /config 에서 꺼 두었다면 다시 켜라고 문서에 적혀 있어요. 세 명령의 차이는 클로드 코드 compact·clear·rewind 차이 글에, CLAUDE.md 를 줄이는 법은 클로드 코드 CLAUDE.md 쓰는 법 글에 있어요.

비슷한 것으로 Autocompact is thrashing 이 있어요. 자동 압축은 됐는데 큰 파일이나 긴 출력이 곧바로 다시 자리를 채우기를 몇 번 반복해서, 헛돌지 않게 멈춘 거예요. 문서가 권하는 방법은 큰 파일을 줄 범위나 함수 단위로 나눠 읽게 하기, /compact keep only the plan and the diff 처럼 남길 것을 적어 압축하기, 큰 파일 일은 서브에이전트에게 맡기기, 필요 없으면 /clear 예요. 서브에이전트는 클로드 코드 서브에이전트 사용법 글에 있어요.

모델 이름을 잘못 적었을 때 나오는 Model 'claude-opus-9' not found 같은 줄도 이 종류(요청 오류)예요. /model 을 아무것도 붙이지 않고 쳐서 목록에서 고르거나, sonnet 같은 짧은 별칭을 쓰라고 문서에 적혀 있어요.

더 깊이: 연결 오류

여기부터는 내 컴퓨터와 서버 사이 길이 막힌 경우예요. 집 인터넷이면 드물고, 회사망·VPN(회사 안 네트워크로 들어가는 보안 통로)·프록시(회사 컴퓨터와 인터넷 사이에서 오가는 것을 거르는 중간 서버)를 쓸 때 자주 생겨요.

먼저 같은 PowerShell 창에서 서버에 연결되는지 봐요.

curl.exe -I https://api.anthropic.com

“Anthropic API 서버에 인사만 건네 보고 답의 머리 부분을 보여 줘”예요. PowerShell 에서는 curl 이 다른 명령의 별칭이라 꼭 curl.exe 라고 쳐야 한다고 문서에 적혀 있어요. 테스트 폴더에서 돌렸더니 첫 줄이 HTTP/1.1 404 Not Found 였어요. 404 는 “그 주소에는 보여 줄 페이지가 없다”는 서버의 답이라, 무엇이든 HTTP 로 시작하는 줄이 오면 서버까지 길은 열려 있는 거예요. “Could not resolve host” 처럼 아무 답도 못 받으면 내 쪽 네트워크가 막고 있는 거고요.

curl.exe 는 되는데 클로드 코드만 연결을 못 한다면, 문서는 ANTHROPIC_BASE_URL 이 남아 있는지 보라고 해요. 이 값이 있으면 클로드 코드는 Anthropic 서버 대신 그 주소로 요청을 보내요. 예전에 시험한 중간 서버 주소가 남아 있고 그 서버가 꺼져 있으면 Connection refused 가 나와요. 테스트 폴더에서 로그인 대신 가짜 키를 설정 파일(fake-key.json)로 주고, 닫힌 주소(127.0.0.1:1)와 없는 주소를 일부러 넣어 돌려 보니 그림처럼 두 가지 문구가 그대로 나왔어요. 가짜 키는 내 컴퓨터 밖으로 나가지 않았어요. 시험이라 다시 하는 횟수(CLAUDE_CODE_MAX_RETRIES)를 0 으로 둬서 바로 떴고, 보통은 몇 번 다시 해 본 뒤에 이 줄이 떠요.

echo $env:ANTHROPIC_BASE_URL

“지금 창에 걸린 ANTHROPIC_BASE_URL 값을 보여 줘”예요. 무언가 나오는데 일부러 넣은 게 아니라면 Remove-Item Env:ANTHROPIC_BASE_URL 로 지우고, settings.json 의 env 필드에 적혀 있지 않은지도 봐요. 그다음 새 터미널에서 claude 를 켜요. 문서는 Docker Desktop 같은 컨테이너 프로그램이 나가는 연결을 가로챌 수 있으니 꺼 보고 다시 해 보라고도 적었어요.

회사 프록시·인증서

회사에서 프록시를 거쳐야 한다면 클로드 코드를 켜기 전에 HTTPS_PROXY 에 프록시 주소를 넣어요. 주소는 회사 전산 담당자에게 물어봐요. 회사 보안 장비가 오가는 내용을 열어 보는 곳이라면 SSL certificate verification failed 나 Self-signed certificate detected 로 시작하는 줄이 떠요. 회사가 쓰는 인증서(믿을 수 있는 서버라는 증명서)를 클로드 코드가 모르는 거예요.

• 할 일: 회사 인증서 묶음 파일을 받아 NODE_EXTRA_CA_CERTS 에 그 파일 경로를 넣어요. 파일은 전산 담당자에게 받아요.
• 하지 말 것: 인터넷 글에서 흔히 보이는 NODE_TLS_REJECT_UNAUTHORIZED=0 은 인증서 검사를 통째로 꺼 버려서 쓰지 말라고 문서에 적혀 있어요.

인증서 오류는 다시 해도 같은 결과라서 클로드 코드가 처음 한 번에 바로 보여 줘요(2.1.199 버전부터). 설치 단계에서 나는 인증서 오류는 설치 글에 따로 있어요.

재시도 손보기

느린 네트워크나 밤새 돌리는 자동 작업이라면 다시 하는 방식을 환경 변수로 바꿀 수 있어요. 문서의 표 가운데 자주 쓸 만한 셋이에요.

환경 변수	기본값	용도
CLAUDE_CODE_MAX_RETRIES	10	다시 하는 횟수, 스크립트에선 줄여 빨리 실패
API_TIMEOUT_MS	600000(10분)	느린 네트워크·프록시면 늘림
CLAUDE_CODE_RETRY_WATCHDOG	없음	1 이면 429·529 를 끝없이 다시(무인 작업용)

출처: 클로드 코드 오류 참조 문서 “재시도 동작 조정”. 10월 9일 확인.

매번 걸기 번거로우면 settings.json 의 env 필드에 적어 둬요. 적는 형식은 settings.json 글의 “env: 환경 변수 묶음”에 있어요. WATCHDOG 는 사람이 지켜보지 않는 작업에서 서버가 붐빌 때 포기하지 않게 하는 것이라, 평소 쓰는 터미널에서는 켜 둘 이유가 별로 없어요.

오류 없이 이상할 때

빨간 줄은 없는데 멈춘 것 같거나 답이 평소보다 못할 때도 있어요.

• 멈춘 것 같아요: Ctrl+C 로 지금 일을 멈춰 봐요. 그래도 안 되면 터미널을 닫고 다시 켜요. 대화는 안 없어져요. 같은 폴더에서 claude --resume 으로 골라 이어 하면 돼요.
• 메모리 경고가 떠요: 한 세션이 메모리를 2.5GB 넘게 쓰면 경고가 떠요. 다시 켜서 claude --continue 로 이어 하면 새 프로그램에서 같은 대화를 이어 가요.
• 답이 평소보다 못해요: 문서는 클로드 코드가 모델을 몰래 바꾸지 않는다고 적었어요. /model 로 생각한 모델이 맞는지, /effort 로 effort 수준이 낮지 않은지, /context 로 대화가 꽉 차지 않았는지부터 봐요.
• 엉뚱한 답이 나왔어요: 대화로 바로잡기보다 Esc 를 두 번 누르거나 /rewind 로 그 요청 앞으로 되돌린 뒤 더 자세히 다시 요청하는 쪽이 낫다고 해요. 틀린 시도가 대화에 남으면 뒤 답이 거기에 끌려가서예요.

알리기: /feedback

위 방법으로도 안 풀리면 Anthropic 에 알려요. 클로드 코드 안에서 /feedback 을 치면 대화 기록과 내가 적은 설명을 Anthropic 에 보내고, 내용을 채운 GitHub 이슈(공개 게시판의 문제 신고 글)를 열지도 물어봐요. 보내려면 로그인이 되어 있어야 해요. 대화 기록이 같이 가니, 비밀번호 같은 것이 대화에 있었다면 보내기 전에 한 번 생각해요.

그 밖에 문서가 적은 곳은 셋이에요. status.claude.com 에서 지금 장애 공지 보기, GitHub 의 anthropics/claude-code 저장소에서 같은 문제가 이미 올라왔는지 찾기, 그리고 계정·결제·구독 문제는 claude.ai 왼쪽 아래 내 이름 머리글자 > Get help 로 지원팀에 묻기예요. 클로드 코드 오류 문서가 아니라 지원팀 몫이에요.

코덱스·안티그래비티는

OpenAI 의 코덱스 CLI 와 구글의 안티그래비티 CLI(예전 제미나이 CLI)도 터미널 코딩 도구라 오류를 만나는 자리가 비슷해요. 오류를 찾고 알리는 도구만 비교했어요.

항목	클로드 코드	코덱스 CLI	안티그래비티 CLI
점검 명령	claude doctor, /doctor	codex doctor	읽은 문서에 없음(미확인)
오류 문구 문서	오류 참조(문구별 표)	CLI 오류 문구 표는 못 찾음(미확인)	Troubleshooting 네 가지
문제 알리기	/feedback	/feedback	/feedback
남은 한도 보기	/usage	/status	/usage(/quota)
서비스 상태 페이지	status.claude.com	읽은 문서에 없음	읽은 문서에 없음

출처: code.claude.com 오류 참조·문제 해결, learn.chatgpt.com 코덱스 명령 참조(codex doctor·/feedback·/status), antigravity.google CLI Troubleshooting·CLI reference. 10월 9일 확인.

코덱스는 codex doctor 가 클로드 코드의 claude doctor 와 같은 자리예요. 문서는 지원 문의를 하기 전이나 설치가 망가졌을 때 쓰는 진단 보고서라고 하고, 설치·설정·로그인·실행 환경·깃·터미널 등을 본다고 적었어요.

안티그래비티 CLI 문서의 Troubleshooting 쪽은 오류 문구 네 가지만 다뤄요. agy 명령을 못 찾을 때(PATH), 로그인 정보를 담는 키체인이 잠겼을 때, SSH 너머에서 붙여 넣기가 안 될 때, 자동 업데이트 잠금 파일이 남았을 때예요. 서버가 바쁠 때 같은 실행 중 오류를 문구별로 모은 쪽은 이번에 찾지 못했어요.

제 생각에는 이번에 찾은 문서 가운데서는 클로드 코드 쪽 오류 문서가 가장 촘촘했어요. 문구 하나하나에 이유와 할 일이 붙어 있고 한국어 문서도 있어요. 대신 그만큼 길어서, 처음엔 이 글의 분류 그림으로 어느 쪽인지 가른 다음 Ctrl+F 로 찾는 게 편해요. 세 도구의 압축·캐시·요금제 차이는 클로드 코드·코덱스·제미나이 CLI 비교 글에 있어요. 코덱스와 안티그래비티를 처음 쓰는 법은 코덱스 CLI 사용법 처음부터, 안티그래비티 CLI 사용법 처음부터 글이에요.

오류별 먼저 할 일

여기까지를 한 표로 모았어요. 문구 앞부분만 맞춰 보면 돼요.

문구 앞부분	어느 쪽	먼저 할 일
API Error: 500	서버	status.claude.com, 1분 뒤 try again
Repeated 529 Overloaded	서버(한도 아님)	몇 분 뒤 다시 또는 /model
may be incomplete	연결 끊김	continue
Not logged in, Login expired	로그인	/login
You’ve hit your … limit	내 한도	적힌 시각까지, /usage
429, Credit balance is too low	API 키	/status 의 API key 줄
Context limit reached	대화 크기	/compact 또는 /clear
Unable to connect, SSL	내 네트워크	curl.exe -I, BASE_URL·프록시

출처: 클로드 코드 오류 참조 문서. 10월 9일 확인.

한국에서 되나

질문	답
한국에서 되나	됨(Anthropic 지원 국가 목록에 South Korea)
무슨 요금제	오류 문서·doctor·/feedback 은 요금제 조건 없음
한국어 문서	있음(code.claude.com/docs/ko/errors)
버전 숫자	이 글은 2.1.295 기준

출처: 클로드 코드 문서 오류 참조, anthropic.com 지원 국가 목록. 10월 9일 확인.

다음에 볼 글

아직 안 깔았다면 클로드 코드 설치 윈도우 초보용, 처음 쓰는 법은 클로드 코드 사용법 처음부터가 먼저예요. 한도 오류가 잦다면 클로드 코드 사용량 확인하는 법, 설정이 꼬였다면 클로드 코드 settings.json 설정하는 법으로 이어져요.

이 글의 내용은 2026년 10월 9일, 클로드 코드 2.1.295 기준이에요. 오류 문구는 버전마다 조금씩 바뀌어서(문서에도 “2.1.227 전에는 이렇게 적혔다” 같은 줄이 많아요), 글과 글자가 다르면 앞 몇 단어로 오류 참조 문서를 찾아보세요.

이 글이 들어간 총정리: 클로드 코드 사용량 아끼는 법

참고한 자료

2026년 10월 9일에 확인했어요. 클로드 코드 문서는 영어 문서와 한국어 문서(/docs/ko/)를 같이 봤어요. 다시 확인할 날: 11월 9일(오류 문구·재시도 기본값), 12월 9일(코덱스·안티그래비티 점검 명령).

• Error reference (클로드 코드 공식 문서, 오류 찾기 표·자동 재시도·서버 오류·사용 한도·인증·네트워크·요청 오류·응답 품질·오류 보고)
• 오류 참조 (클로드 코드 공식 한국어 문서, 캡처한 페이지)
• Troubleshooting (클로드 코드 공식 문서, 증상별 문서 표·/doctor 와 claude doctor·멈춤·메모리·Autocompact is thrashing)
• 문제 해결 (클로드 코드 공식 한국어 문서, 캡처한 페이지)
• Troubleshoot installation and login (클로드 코드 공식 문서, 로그인 초기화)
• Supported countries (Anthropic, South Korea)
• Command line options · Slash commands (OpenAI 코덱스 공식 문서, codex doctor·/feedback·/status)
• Troubleshooting (안티그래비티 CLI 공식 문서, Quick reference 네 가지)
• CLI reference (안티그래비티 CLI 공식 문서, /feedback·/usage)

같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표