Claude 자주 겪는 에러 6가지 원인과 해결 방법

밤 11시, 한참 잘 굴러가던 Claude 대화창에 갑자기 "You've hit your limit for Claude messages"가 떴다. 마감은 코앞인데 5시간을 기다리라니. 며칠 뒤엔 API로 옮겨 자동화를 돌렸더니 이번엔 401 authentication_error가 떨어졌다. 분명 어제까지 잘 됐는데. Claude를 실무에 본격적으로 쓰다 보면 이런 벽을 반드시 만난다.

저도 프롬프트 분석 서비스를 운영하면서 claude.ai 웹과 Anthropic API 양쪽에서 같은 에러들을 수십 번 밟았습니다. 결론부터 말하면, 대부분은 **"대화 히스토리 누적"과 "키·포맷 실수"**라는 두 뿌리에서 나옵니다. 이 글에서는 가장 자주 나오는 6가지를 실제 메시지와 함께, 멘토가 옆에서 알려주듯 원인과 단계별 해결법으로 풀어보겠습니다.

참고: 이 글은 HTTP 529 Overloaded 에러는 다루지 않습니다. 그건 별도 주제라 Claude API 529 Overloaded 에러 대응에서 따로 정리했습니다. 여기서 다루는 웹의 "capacity constraints" 거부와는 표면이 다른 별개 현상입니다.

큰 그림: 에러는 "웹"과 "API" 두 갈래다

Claude 에러는 어디서 났는지를 먼저 구분해야 처방이 달라집니다.

구분	대표 에러	핵심 원인	누가 자주 겪나
claude.ai 웹	5시간 한도 도달	세션 사용량 한도 + 긴 대화 누적	일반 사용자
claude.ai 웹	capacity constraints 거부	인프라 고수요/부하	피크 시간·무료 티어
claude.ai 웹	로그인 루프·세션 만료	쿠키 손상·확장프로그램·VPN	모든 사용자
Anthropic API	401 authentication_error	API 키 문제	개발자
Anthropic API	400 prompt is too long	컨텍스트 윈도 초과	에이전트·긴 대화
Anthropic API	400 invalid_request_error	thinking 변형·prefill 미지원	신형 모델 사용자

이제 하나씩 보겠습니다.

1. claude.ai 웹 — 5시간 사용량 한도 도달

가장 흔하게 보는 메시지입니다.

You've hit your limit for Claude messages.
5-hour limit reached — resets [시각].
(사전 경고) Approaching 5-hour limit.

원인

claude.ai는 약 5시간 단위 세션 한도로 사용량을 관리합니다. Free든 Pro든 적용되며, 한도는 고정된 메시지 개수가 아니라 다음 요소들에 따라 출렁입니다.

• 선택한 플랜 (Free / Pro / Max)
• 메시지 길이와 현재 대화의 누적 길이
• 첨부 파일 크기
• 선택한 모델 — Opus 같은 고비용 모델일수록 빨리 소진
• Anthropic의 현재 capacity

여기서 핵심은 누적 길이입니다. 긴 대화 하나를 계속 이어가면, 매 요청마다 그 대화의 전체 히스토리가 다시 전송됩니다. 즉 대화가 길어질수록 메시지 한 번당 소모량이 눈덩이처럼 커집니다. "분명 몇 번 안 보냈는데 벌써 한도?"의 진짜 범인이 바로 이겁니다.

단계별 해결

1. 한도 메시지에 표시된 리셋 시각까지 대기 — 보통 마지막 사용 시점 기준 약 5시간 후입니다.
2. 긴 대화를 무한정 이어가지 말고 작업 단위로 "새 대화"를 시작하세요. 누적 히스토리를 끊는 게 가장 효과적입니다.
3. 무거운 작업이 아니면 Opus 대신 Sonnet/Haiku 계열 가벼운 모델로 전환해 메시지당 소모를 줄입니다.
4. 첨부는 꼭 필요한 부분만 작게 잘라 올립니다. 대용량 첨부가 한도를 빠르게 깎습니다.
5. 자주 친다면 상위 플랜(Pro→Max)으로 올리거나, 유료 플랜 설정에서 **usage credits(추가 사용 크레딧)**를 켭니다.
6. 실시간 자동화·대량 작업이라면 웹 대신 Anthropic API로 옮겨 rate limit 기반으로 운영하는 걸 검토하세요.

솔직히 말하면, 한도를 자주 친다는 건 워크플로 신호입니다. "대화 하나에 모든 걸 욱여넣는" 습관을 "작업마다 새 대화"로 바꾸는 것만으로 체감 한도가 크게 늘어납니다. Anthropic 공식 설명도 "Pro 기준 짧은 대화 시 5시간당 최소 45메시지 이상"이라는 하한 예시일 뿐, 긴 대화에선 그보다 훨씬 적게 보내고도 막힐 수 있습니다.

2. claude.ai 웹 — "capacity constraints" 거부

Due to unexpected capacity constraints, Claude is unable to
respond to your message. Please try again soon.

원인

Anthropic 인프라가 수요를 못 따라갈 때 나오는 부하 관리 메시지입니다. 공식적으로는 "장애(outage)"가 아니라 정상적인 용량 관리로 분류됩니다. 대략 PT 오전 9시~정오 같은 피크 시간대나 무료 티어에서 더 자주 뜹니다.

다만 주의할 점이 있습니다. 2026년 6월 초처럼 실제 글로벌 장애로 번지는 경우(로그인은 되는데 응답이 전혀 안 됨)도 있었습니다. 광범위하게 안 되면 진짜 장애일 수 있으니 단순 부하로만 단정하지 마세요.

단계별 해결

1. 수 분 대기 후 같은 메시지 재전송 — 일시적 부하면 대부분 곧 풀립니다.
2. 응답이 길어질 것 같으면 요청을 짧게 쪼개 재시도합니다. 부분 응답 중 끊기는 케이스가 완화됩니다.
3. 광범위하게 안 되면 status.claude.com에서 진행 중인 인시던트를 확인하세요. 있으면 내 문제가 아니니 복구를 기다립니다.
4. 피크 시간대(PT 오전)를 피하거나, 빈번하면 유료 플랜으로 우선순위를 확보합니다.
5. 프로그램 자동화라면 지수 백오프(exponential backoff) 재시도 로직으로 일시 거부를 흡수합니다.

3. claude.ai 웹 — 로그인 루프 / 세션 만료

There was an error logging you in.
(앱·연동도구) Unauthorized. Your Claude session may have expired.

원인

로그인이 빙빙 돌거나 자꾸 로그아웃되는 건 보통 클라이언트 환경 문제입니다.

• 브라우저 쿠키 차단·캐시 손상으로 세션 토큰이 stale 해짐
• VPN/프록시 exit node가 Anthropic의 부정사용 탐지에 걸려 세션이 깨짐
• 광고/스크립트 차단 확장(uBlock, Privacy Badger 등)이 인증 쿠키·스크립트를 막아 루프 유발
• Anthropic이 auth 업데이트를 푸시한 직후 기존 세션이 무효화

단계별 해결

1. 완전 로그아웃 후 claude.ai 쿠키·캐시를 지우고 다시 로그인합니다. 손상된 토큰 제거가 가장 효과적입니다.
2. 쿠키/스크립트 차단 확장을 일시 비활성화하거나, 시크릿 창에서 모든 확장을 끈 채 로그인합니다.
3. VPN/프록시를 끄고 시도합니다. 일부 exit node가 탐지에 걸립니다.
4. 다른 브라우저로 전환합니다(Chrome 루프 시 Firefox/Edge).
5. 서드파티 도구(메뉴바 앱·OAuth 연동)에서 만료가 반복되면 해당 앱에서 재인증/토큰 재발급을 수행합니다. 도구 쪽 refresh 토큰 버그일 수 있습니다.
6. 그래도 안 되면 status.claude.com에서 auth 관련 인시던트를 확인하고 잠시 대기합니다.

4. API 401 authentication_error — 키 인증 실패

여기서부터는 개발자 영역입니다.

{"type":"error","error":{"type":"authentication_error","message":"...invalid x-api-key..."}}

원인

순수하게 API 키 문제입니다. 흔한 경우는 이렇습니다.

• 키 오타·앞뒤 공백
• 폐기·회전된 옛 키를 그대로 사용
• 환경변수 ANTHROPIC_API_KEY 미설정 또는 잘못된 키 로드
• 헤더 누락(x-api-key 미전송)

혼동하기 쉬운 형제 에러를 정리해두면 디버깅이 빨라집니다.

코드	타입	의미
401	authentication_error	키 자체가 잘못됨
403	permission_error / billing_error	키는 유효하나 권한이 없거나 결제(크레딧) 문제

AWS 경유(Claude Platform on AWS)라면 AWS 자격증명·SigV4 서명 문제도 401로 나타납니다.

단계별 해결

1. Anthropic Console에서 키가 활성 상태인지 확인하고, 의심되면 새 키를 발급해 교체합니다.
2. 요청 헤더에 x-api-key가 제대로 들어가는지 확인합니다(SDK는 ANTHROPIC_API_KEY를 자동 로드).
3. 환경변수에 따옴표·줄바꿈·공백이 섞이지 않았는지 점검합니다. 복붙 시 가장 흔한 실수입니다.

# 끝에 보이지 않는 공백/줄바꿈이 있는지 확인
printf '%q\n' "$ANTHROPIC_API_KEY"

4. 키가 의도한 조직/워크스페이스에 속하는지 확인합니다. 다른 워크스페이스 키를 쓰면 401/403이 납니다.
5. 에러 응답의 request_id를 보관해, 재현되면 Anthropic 서포트에 제출합니다.
6. AWS 경유라면 AWS 자격증명·리전·SigV4 서명을 별도로 점검합니다.

5. API 400 — prompt is too long (컨텍스트 초과)

{"type":"invalid_request_error","message":"prompt is too long: 233153 tokens > 200000 maximum"}

원인

입력 토큰 합계가 모델 컨텍스트 윈도를 넘은 겁니다. 여기서 입력은 system 프롬프트 + 모든 user/assistant 메시지 + 첨부·도구 출력을 다 합친 값입니다. 표준 윈도는 200K이고 일부 모델은 1M 베타를 지원합니다(233153 같은 구체 수치는 예시일 뿐, 모델마다 다릅니다).

웹 한도와 똑같이, 가장 흔한 원인은 대화 히스토리 무한 누적입니다. 채팅이 길어질수록 매 요청에 과거 전체가 재전송됩니다. 그리고 max_tokens(출력 예산)도 윈도를 함께 차지하므로, input + max_tokens 합이 윈도를 넘으면 발생합니다.

단계별 해결

1. 요청 전에 **Token Counting API(count_tokens)**로 입력 토큰을 미리 계산해 초과를 사전 차단합니다.
2. 대화 히스토리를 동적 트리밍(오래된 턴 제거)하거나, 중간중간 요약본으로 압축해 재투입합니다.
3. 관련 없는 첨부·붙여넣은 대용량 텍스트를 빼고 필요한 부분만 선별합니다.
4. max_tokens를 과도하게 크게 잡지 말고 실제 필요치로 낮춰 input과의 합을 윈도 안에 맞춥니다.
5. 정말 긴 컨텍스트가 불가피하면 1M 컨텍스트 모델/베타로 전환하거나 RAG로 필요한 청크만 검색해 주입합니다.
6. 에이전트/툴을 만든다면, 이 400을 "컨텍스트 초과"로 감지해 abort 대신 자동 압축·트리밍 후 재시도하도록 처리합니다.

6. API 400 invalid_request_error — thinking 변형 / prefill 미지원

신형 모델(Opus 4.x, Sonnet 4.6 등)로 옮겼을 때 갑자기 터지는 포맷 에러입니다.

`thinking` or `redacted_thinking` blocks in the latest assistant
message cannot be modified...

Prefilling assistant messages is not supported for this model.

원인

두 가지가 대표적입니다.

• (1) thinking 블록 변형: extended thinking을 쓸 때, 직전 assistant 턴의 thinking/redacted_thinking 블록을 편집·재정렬·필터링·재구성해서 되돌려보내면 거부됩니다. 반드시 원본 그대로, 빈 thinking 블록까지 전부 그대로 재전송해야 합니다.
• (2) prefill 미지원: 같은 신형 모델들은 마지막 assistant 메시지를 미리 채우는 prefill을 더 이상 지원하지 않습니다.

그 외 잘못된 role 순서·필드 누락 등 일반 포맷 오류도 400으로 묶입니다.

단계별 해결

1. thinking 사용 시: 응답으로 받은 thinking/redacted_thinking 블록을 한 글자도 바꾸지 말고 그대로 다음 요청에 포함합니다. 콘텐츠 타입을 필터링한다면 두 종류 모두 살려야 합니다.
2. prefill로 출력을 강제하던 코드는 제거하고, 대신 structured outputs(output_config.format) 또는 system 프롬프트 지시로 형식을 유도합니다.
3. 에러 메시지 앞의 위치 인덱스(예: messages.1.content.0)로 문제 블록을 특정해 수정합니다.
4. messages 배열의 role 교대(user/assistant 번갈아), 필수 필드, content 블록 구조가 스키마에 맞는지 검증합니다.
5. SDK의 typed 예외를 잡아 처리합니다. 문자열 매칭 대신 타입으로 분기하세요.

import anthropic
client = anthropic.Anthropic()
try:
    resp = client.messages.create(...)
except anthropic.BadRequestError as e:
    # 400 계열: 포맷/컨텍스트 초과
    print(e.request_id, e.message)
except anthropic.AuthenticationError as e:
    # 401: 키 문제
    print("키 점검 필요")

6. 재현되면 request_id와 함께 모델별 마이그레이션 문서를 확인하세요. 신형 모델 전환 시 prefill/thinking 규약이 바뀝니다.

실전 팁 — Do's & Don'ts

Do (이렇게)	Don't (이러지 말 것)
작업 단위로 새 대화 시작	대화 하나에 모든 걸 욱여넣기
가벼운 모델(Sonnet/Haiku)로 일상 작업	모든 걸 Opus로 돌려 한도 소진
요청 전 count_tokens로 미리 검증	토큰 초과를 런타임에서야 발견
에러를 SDK typed 예외로 분기	에러 메시지 문자열 매칭에 의존
자동화에 지수 백오프 재시도	거부 즉시 abort/무한 즉시 재시도
thinking 블록 원본 그대로 재전송	thinking 블록을 가공·필터링
status.claude.com 먼저 확인	내 코드부터 의심하며 시간 낭비

추가로 챙겨두면 좋은 3가지입니다.

1. request_id는 항상 로깅하세요. Anthropic 서포트 문의 시 가장 빠른 단서입니다.
2. 에러 메시지 문구는 모델·버전에 따라 바뀔 수 있습니다. 문자열에 의존하지 말고 HTTP 코드와 SDK 예외 타입으로 처리하세요.
3. 웹과 API를 용도로 분리하세요. 탐색·대화는 웹, 반복·대량·자동화는 API가 정답입니다. 한쪽에 무리하게 몰면 한도와 비용 양쪽에서 손해입니다.

마무리 — 결국 두 가지로 수렴한다

지금까지 6가지를 봤지만, 패턴은 단순합니다.

• 웹 쪽 문제(한도·로그인): 긴 대화 누적을 끊고, 쿠키·확장·VPN을 정리하면 대부분 해결됩니다.
• API 쪽 문제(401·400): 키를 깨끗하게 관리하고, 컨텍스트를 트리밍하고, 신형 모델의 thinking/prefill 규약을 지키면 막힙니다.

불확실한 부분은 정직하게 짚고 갑니다. 5시간 한도의 정확한 메시지 개수와 리셋 타이밍, 컨텍스트 윈도 크기는 플랜·모델·대화 길이·현재 capacity에 따라 변동합니다. 고정값으로 외우지 말고, 막혔을 때 위의 체크리스트를 순서대로 밟는 게 가장 빠릅니다.

다음 행동을 추천드립니다. (1) 자주 막힌다면 지금 쓰는 대화 습관을 "작업마다 새 대화"로 바꿔보세요. (2) API를 쓴다면 count_tokens 검증과 typed 예외 처리를 미리 코드에 심어두세요. 529 Overloaded 같은 부하 계열 에러까지 함께 대비하고 싶다면 Claude API 529 Overloaded 에러 대응 가이드와 AI 도구 활용 글 모음도 이어서 읽어보시길 권합니다.

참고 출처

• Anthropic API 에러 공식 문서
• Claude 서포트센터 — 사용량·트러블슈팅
• Claude 시스템 상태 페이지