Claude Code Rate Limit Reached 해결: 사용량·컨텍스트·API 제한 구분하기

Claude Code에서 API Error: Rate limit reached가 뜨면 요청이 어떤 제한에 걸려 멈췄다는 뜻이지만, 이 한 줄만으로는 어떤 제한인지 알 수 없습니다. 구독 요금제의 세션·주간 한도일 수도, 서버 쪽의 짧은 일시 제한일 수도, API 키나 클라우드 프로젝트의 429일 수도, 1M 컨텍스트 권한 문제일 수도 있고, 대처는 각각 다릅니다. 2026년 10월 5일 기준 Claude Code 공식 오류 참조는 이 경우들을 더 구체적인 메시지로 나눠 보여 주므로, 먼저 화면에 찍힌 원문을 그대로 확인하세요.

지금 작업이 멈춰 있다면 순서는 이렇습니다. 같은 메시지를 연달아 다시 보내지 말고(오류가 보일 때는 자동 재시도가 이미 끝난 뒤입니다), 세션을 닫지 않은 채 /usage로 한도와 초기화 시각을, /status로 어떤 계정과 인증 정보로 연결됐는지 확인합니다. 구독 한도라면 Claude Code v2.1.234 이상은 초기화 뒤 멈춘 작업을 스스로 이어서 실행합니다. 사용량이 남아 있는데도 같은 오류가 계속되면 재설치나 추가 결제보다 모델 변형, 계정, 설치 상태를 먼저 확인하고 증거를 남겨 보고하는 편이 빠릅니다.

Rate limit reached 계열 메시지: 원문별 의미와 다음 행동

화면의 메시지를 아래 표 왼쪽 열과 맞춰 보세요. 3:45pm 같은 시각은 예시이며, 실제 메시지에는 계정에 해당하는 시각이 표시됩니다.

세션 한도와 주간 한도는 동시에 차감됩니다. 그래서 대규모 워크플로처럼 한꺼번에 많이 쓰면 세션 창이 초기화되기 전에 주간 한도가 먼저 바닥날 수 있습니다. 한도가 다 차기 전에는 You've used 85% of your session limit · resets 3:45pm 같은 경고가 먼저 나오기도 합니다. Pro와 Max의 세션 한도는 5시간마다, 주간 한도는 계정마다 정해진 요일과 시각에 초기화되며(claude.ai의 Settings > Usage에서 확인), 이 사용량은 claude.ai, Claude Code, 데스크톱 앱, IDE가 함께 씁니다. 몇 시간 또는 몇 번의 프롬프트에 해당하는지는 공개된 수치가 없습니다.

Remote Control이나 백그라운드 세션처럼 아무도 화면을 보고 있지 않은 세션에서 Fable limit reached · continuing on Fable 5.1 uses usage credits로 시작하는 줄이 보인다면 사정이 다릅니다. 사용 크레딧 사용 동의 창에 아무도 답하지 않아 요청이 아예 전송되지 않은 것이므로, 세션이 실행 중인 곳에서 동의 창에 답하거나 /model로 모델을 바꾸면 됩니다.

Rate limit reached 문구만 보일 때 어떤 제한인지 좁히는 순서

이 짧은 문구는 지금도 실제로 나올 수 있습니다. Claude Code 훅 문서의 StopFailure 예시를 보면 error가 rate_limit, error_details가 429 Too Many Requests일 때 화면 문구가 API Error: Rate limit reached로 기록됩니다. 다만 어떤 버전이나 연결 방식에서 구체적인 메시지 대신 이 문구가 나오는지는 공식 문서에 적혀 있지 않습니다. 그래서 문구 자체보다 아래 네 가지 확인으로 종류를 좁힙니다.

1. /usage로 한도 사용률과 초기화 시각 보기. 세션이나 주간 막대가 100%에 가깝다면 구독 한도입니다. /cost와 /stats는 같은 화면을 여는 별칭입니다.
2. /status로 연결 경로 보기. 버전, 모델, 계정, 연결 상태가 나옵니다. 남은 사용량을 보는 화면은 아닙니다. 구독으로 쓰는 줄 알았는데 API 키로 연결돼 있다면, 환경 변수 ANTHROPIC_API_KEY가 요청을 구독 대신 API 과금 경로로 보내는 중일 수 있고, 이때는 그 키의 등급에 맞는 한도가 적용됩니다.
3. /model로 모델 이름에 [1m]이 붙어 있는지 보기. Opus 4.6과 Sonnet 4.6의 [1m] 변형은 요금제에 따라 사용 크레딧이 있어야 쓸 수 있습니다(아래 1M 컨텍스트 항목 참고).
4. claude --version과 /doctor로 설치 상태 보기. /doctor는 중복되거나 남아 있는 설치, PATH 문제를 점검합니다. 셸에서 claude doctor를 실행하면 설치 상태를 읽기 전용으로 진단합니다.

같은 오류가 자주 반복된다면 StopFailure 훅을 걸어 error와 error_details 값을 파일로 남겨 두세요. 나중에 보고할 때 어떤 종류의 실패였는지 보여 주는 근거가 됩니다. 이 훅은 기록과 알림 전용이라 작업 흐름을 바꾸지는 못합니다.

멈춘 작업을 같은 세션에서 이어가는 방법

핵심은 세션을 닫지 않고, 같은 요청을 무작정 다시 보내지 않는 것입니다.

Claude Code는 일시적인 실패를 지수 백오프로 최대 10번까지 다시 시도한 뒤에야 오류를 보여 줍니다. 일시적인 429 제한도 여기에 포함되며, claude.ai 구독으로 로그인한 경우 v2.1.199부터는 요금제 할당량 헤더가 없는 429도 자동으로 재시도합니다. 재시도하는 동안에는 스피너에 Retrying in Ns · attempt x/y가 표시됩니다. 오류 문구가 화면에 나왔다면 적용 가능한 재시도는 이미 끝난 것이므로, 같은 메시지를 곧바로 다시 보내도 대개 같은 결과가 나옵니다.

다시 지시하기 전에 어디까지 진행됐는지도 확인하세요. Claude가 텍스트나 도구 호출을 이미 끝낸 뒤에 서버 오류나 연결 끊김이 오면, Claude Code는 같은 도구가 두 번 실행되지 않도록 그 요청을 다시 실행하지 않고 완료된 부분을 남긴 채 The response above may be incomplete를 표시합니다. 한도에 걸려 멈춘 경우에도 그 직전까지의 파일 수정이나 명령 실행은 이미 끝났을 수 있으니, git status나 git diff로 바뀐 내용을 보고 남은 부분만 요청하는 편이 안전합니다.

서브에이전트가 멈추면 Agent terminated early due to an API error: 뒤에 실제 오류가 붙어 나옵니다. 콜론 뒤의 내용을 위 표에서 찾아 해당 조치를 하고, 원인이 풀린 뒤 Claude에게 작업을 다시 시키거나 서브에이전트를 재개하세요. 서브에이전트가 이미 텍스트를 만들어 둔 상태였다면 Claude는 오류 대신 미완료로 표시된 부분 결과를 받습니다.

구독 한도에 걸렸을 때: 초기화 후 자동 이어서 실행

Claude Code v2.1.234 이상에서 claude.ai 구독으로 로그인한 대화형 세션은 사용 한도에 걸리면 세션 안에서 기다렸다가 초기화 뒤 작업을 스스로 이어갑니다. 이 기능은 기본으로 켜져 있고, 기다리는 동안 화면 아래에 다음 두 줄이 보입니다.

Usage limit reached · limit resets 3:45pm
Continuing automatically at 3:45pm · esc to cancel

초기화되면 대화에 Usage limit reset · continuing automatically가 나타나고 Claude가 멈춘 지점부터 작업을 이어받습니다. 마지막 메시지를 다시 보내지 않으므로 같은 지시가 두 번 실행되지 않습니다. 이 대기가 제대로 끝나려면 몇 가지 조건이 있습니다.

• 세션을 열어 둬야 합니다. Claude Code를 종료하면 나중에 세션을 재개해도 대기가 다시 시작되지 않습니다. /login으로 계정을 바꾸거나, 대화를 지우거나 되감거나, /resume으로 다른 세션을 열어도 대기가 끝납니다.
• 대기 중에 새 프롬프트를 보내면 기다리는 대신 그 프롬프트가 바로 전송됩니다.
• 권한 확인은 평소처럼 묻습니다. 자리를 비운 사이 이어진 작업이 권한 창에서 멈춰 있을 수 있습니다.
• 다시 한도에 걸리면 연속 두 번까지만 대기를 다시 걸고, 그 뒤에는 Automatic continue stopped after repeated usage-limit hits · /rate-limit-options to try again을 표시하고 멈춥니다.
• 컴퓨터가 30분 넘게 잠자기 상태였고 그사이 한도가 초기화됐다면 Press enter to continue가 표시되니 Enter를 누르면 됩니다.

주간 한도처럼 초기화가 24시간보다 먼 경우, 다른 계열 모델을 쓰는 중에 Opus나 Sonnet 계열 한도에 걸린 경우, Remote Control이나 에이전트 팀의 팀원 세션에서는 대기가 자동으로 시작되지 않습니다. 이때는 자기 터미널에서 한도에 걸리면 사용 한도 옵션 메뉴가 초기화 창마다 한 번 열리고, 직접 /rate-limit-options를 실행해 열 수도 있습니다. 메뉴에서는 Wait here, then continue automatically로 시작하는 항목을 골라 대기를 시작하거나, 사용 크레딧을 추가하거나, 요금제를 올릴 수 있습니다. 백그라운드 세션과 -p 실행에서는 이 대기 항목이 없고, API 키·클라우드 공급자·사용량 기반 과금은 요청마다 과금되므로 기다릴 초기화 자체가 없습니다.

대기 중에 /usage-credits로 사용 크레딧 추가를 마치거나 /model로 모델을 바꾸면 Claude Code가 사용 가능 여부를 다시 확인하고, 가능하면 바로 이어갑니다. 브라우저에서 따로 결제하거나 요금제를 올린 경우에는 다시 확인하지 않습니다. 사용 크레딧은 포함 한도를 넘은 사용량을 표준 API 요금으로 결제하는 방식이며, 이 크레딧을 쓰는 동안에는 프롬프트 캐시 유지 시간이 1시간에서 5분으로 줄어듭니다. 크레딧과 한도 초기화가 어떻게 다른지는 Claude 클라우드 세션 크레딧·사용 크레딧·한도 초기화 차이, 비용 판단은 Claude 추가 사용 요금: 크레딧, Max, Claude Code 청구 경로 판단, 요금제를 올릴지는 Claude Pro vs Max 2026: 가격, Claude Code 제한, Max 손익분기점에서 이어서 볼 수 있습니다.

자동 이어서 실행을 끄려면 /config에서 Continue automatically at usage limit를 끄거나 사용자 설정에 autoContinueAtUsageLimit: false를 넣습니다. 데스크톱 앱 Code 탭의 세션 한도 카드에 있는 Auto-continue when limits reset 체크박스는 별개 설정이라 따로 꺼야 하며, 주간 한도 카드에는 이 체크박스가 없습니다. v2.1.234보다 오래된 버전에는 이 대기 기능이 없으므로 초기화 시각이 지난 뒤 직접 이어서 진행하라고 지시해야 합니다.

모델을 바꾸면 풀리는 경우: Opus·Sonnet 계열 한도와 1M 컨텍스트 변형

You've hit your Opus limit나 You've hit your Sonnet limit는 그 계열 모델에만 걸리는 한도라서, /model로 다른 계열 모델을 고르면 바로 작업을 계속할 수 있습니다. 모델마다 프롬프트 캐시가 따로 있어 바꾼 뒤 첫 요청은 캐시 없이 대화 전체를 다시 읽으므로, 그 한 번은 평소보다 사용량이 큽니다.

1M 컨텍스트 메시지는 원문이 다음과 같습니다.

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

이것은 할당량 소진이 아니라 사용 권한 확인이어서, 세션·주간 한도가 남아 있어도 나타납니다. 해당하는 모델은 Opus 4.6과 Sonnet 4.6의 [1m] 변형뿐이며, 요금제별 조건은 다음과 같습니다.

Fable 5.1, Fable 5, Sonnet 5 이상, Opus 4.7 이상은 Pro를 포함한 모든 요금제에서 처음부터 1M 컨텍스트로 동작하고 [1m] 변형을 따로 고를 필요가 없습니다. 그래서 "opus 1m을 쓰다 Rate limit reached가 뜨면 1m만 해제하고 opus로 다시 시도하라"는 팁은 4.6 세대의 [1m] 변형에 해당하는 이야기이고, 최신 모델에서 같은 오류가 나는 일반적인 원인으로 보기는 어렵습니다.

해결은 /model에서 [1m]이 붙지 않은 변형을 고르는 것이 가장 간단합니다. 1M을 계속 쓰려면 /usage-credits로 사용 크레딧을 켠 뒤 메시지 안내대로 Claude Code를 다시 시작하거나 새 세션을 엽니다. /model로 바꿨는데도 계속 나온다면 설정 파일이나 환경 변수 같은 다른 곳에 1M 모델 ID가 지정돼 있을 수 있고, CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하면 모델 선택 목록에서 1M 변형이 아예 사라집니다. 대화가 200K 토큰을 넘어서 이 오류가 중간에 뜬 경우라면 Claude Code가 표준 컨텍스트 한도 아래로 자동 압축하므로 따로 할 일이 없습니다. 다만 v2.1.172보다 오래된 버전은 /compact를 포함한 모든 요청에서 오류가 반복되니 /clear로 새로 시작해야 합니다.

API 키·클라우드의 429: 인증 정보와 동시 실행 확인

API 키, Amazon Bedrock, Google Cloud로 연결했다면 다음과 같은 메시지가 나옵니다.

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

마지막 문장은 공급자에 따라 해당 서비스의 상태 페이지나 게이트웨이 주소로 바뀝니다. 중간의 프록시나 게이트웨이가 자체 HTML 429 페이지를 돌려준 경우 v2.1.281부터는 · 뒤에 그 페이지 제목(예: Too Many Requests)이 표시됩니다.

먼저 /status로 지금 쓰는 인증 정보가 의도한 것인지 확인하세요. 구독을 쓰려던 사람이 셸에 남아 있던 ANTHROPIC_API_KEY 때문에 등급이 낮은 API 키로 요청을 보내는 경우가 있습니다. 이때는 현재 셸과 셸 프로필에서 그 변수를 지우고 claude를 다시 실행한 뒤, 아직 구독으로 로그인하지 않았다면 /login을 실행합니다. 의도한 키가 맞다면 공급자 콘솔에서 현재 한도를 확인하고 필요하면 상위 등급을 요청합니다. API 키 등급별 한도를 어디서 확인하는지는 Claude Rate Exceeded 오류: 재시도 전에 제한 소유자부터 확인하기에, 어떤 결제 경로가 맞는지는 Claude Code API 키와 구독 결제: 어떤 경로를 써야 할까에서 비교할 수 있습니다.

동시에 나가는 요청을 줄이는 것도 효과가 있습니다. CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY를 낮추거나, 병렬 서브에이전트 수를 줄이거나, 대량 스크립트 작업에는 /model로 더 작은 모델을 쓰세요. 사람이 지켜보지 않는 CI 작업이라면 CLAUDE_CODE_RETRY_WATCHDOG=1을 설정해 429와 529 용량 오류를 횟수 제한 없이 재시도하게 할 수 있습니다. 단 지출 한도나 사용 크레딧 소진을 알리는 429에서는 이 설정이 있어도 즉시 실패합니다.

사용량이 남았는데 Rate limit reached가 뜰 때: 재설치 전 점검

GitHub의 anthropics/claude-code 저장소에는 2026년 2~3월에 이런 보고가 올라왔습니다. Max 구독에서 세션 사용량이 16%인데 모든 요청이 API Error: Rate limit reached로 실패했다는 이슈 #29579(2026년 10월 5일 기준 열려 있음)에는 모델을 바꾸자 풀렸다는 댓글이 달렸고, Cowork에서만 같은 문구가 나오고 다른 계정으로는 정상이었다는 보고(#33120)도 있습니다. 예전에 npm으로 설치한 CLI가 새로 설치한 버전 대신 실행되면서 같은 오류가 났고, npm 설치본을 지워 해결했다는 사례도 공유됐습니다. 모두 개별 사용자의 보고이고 공식적으로 밝혀진 원인은 없습니다. 다만 원인이 사용량이 아니라 모델 변형, 계정, 설치 상태 쪽에서 갈렸다는 점은 확인 순서를 정하는 데 참고가 됩니다.

재설치하거나 사용 크레딧을 사기 전에 다음 순서로 확인하세요.

1. /model에서 [1m] 변형이면 해제하고, 다른 계열 모델로도 한 번 시도합니다.
2. /status에서 로그인 방식이 예상한 구독 계정인지, API 키로 연결돼 있지 않은지 봅니다.
3. 같은 계정으로 claude.ai 채팅이나 다른 기기에서는 되는지, 다른 계정으로는 되는지 비교해 계정 쪽 문제인지 가립니다.
4. claude --version과 /doctor(또는 셸의 claude doctor)로 버전과 중복·잔여 설치, PATH를 확인합니다. npm으로 전역 설치한 예전 버전이 남아 있다고 나오면 그것부터 정리합니다.
5. status.claude.com에서 진행 중인 장애가 있는지 봅니다.

그래도 해결되지 않으면 보고하기 전에 메시지 원문 그대로, 발생 시각과 시간대, claude --version 결과, /status의 로그인 방식과 모델, /usage 화면의 세션·주간 사용률, 다른 모델·계정·기기에서 재현되는지를 기록해 두세요. Claude Code 안에서 /feedback을 실행하면 대화 기록과 설명이 Anthropic으로 전송되고, 내용이 채워진 GitHub 이슈를 여는 선택지도 나옵니다. Amazon Bedrock, Google Cloud, Microsoft Foundry 같은 외부 공급자를 쓰거나 Anthropic 인증 정보가 없으면 /feedback은 로컬 압축 파일을 만들어 주므로, 그 파일을 Anthropic 계정 담당자에게 보내면 됩니다. Team이나 Enterprise 요금제라면 관리자에게도 같은 기록을 공유하세요. 사용량이 남아 있는 상태에서 생긴 오류라면 추가 결제나 요금제 변경이 원인을 해결하지 못할 수 있습니다.

Claude Code가 채팅보다 빨리 한도에 닿는 이유와 줄이는 방법

Claude Code는 요청마다 대화 전체를 보내고, 도구를 쓸 때마다 그 결과를 실은 요청을 한 번 더 보냅니다. 이전 대화는 프롬프트 캐싱 덕분에 캐시 요금으로 다시 읽히지만, 하루 종일 열어 둔 세션에서 한 줄짜리 질문을 해도 대화 전체만큼의 사용량이 듭니다. 캐시 유지 시간(구독은 1시간, 사용 크레딧을 쓰는 중에는 5분)보다 오래 쉬었다가 보낸 첫 메시지는 전체 컨텍스트를 다시 처리하고, 서브에이전트와 예약 작업도 각자 요청을 보냅니다.

아래 개념도는 대화 기록, 관련 파일, 도구 결과가 다음 요청에 포함되고 서브에이전트의 요청도 같은 사용 한도에서 차감되는 구조를 보여 줍니다.

줄이는 방법의 기본은 관련 없는 작업 사이에 /clear로 새로 시작하고(나중에 돌아올 세션은 /rename 후 /resume), 긴 대화를 이어가야 할 때는 /compact에 남길 내용을 지정하는 것입니다. 대부분의 코딩은 Sonnet으로 충분하고, 생각 수준을 낮추거나 쓰지 않는 MCP 서버를 정리해도 사용량이 줄어듭니다. 서브에이전트로 작업을 나눠도 그 요청은 같은 한도에서 차감됩니다. Pro, Max, Team, Enterprise 요금제에서는 /usage 화면이 최근 사용량의 10% 이상을 차지하는 긴 컨텍스트나 캐시 미스 같은 패턴을 짚어 줍니다. 사용 내역을 점검하고 5시간·주간 한도에 맞춰 작업을 계획하는 방법은 Claude Code 토큰 사용량 확인·감사: /usage와 5시간·주간 한도 계획에서 자세히 볼 수 있습니다.

Claude Code Rate limit reached 관련 질문

Claude Code에서 모델을 바꾸면 Rate limit reached가 풀리나요?

메시지에 따라 다릅니다. You've hit your Opus limit나 You've hit your Sonnet limit처럼 모델 계열 한도라면 /model로 다른 계열로 바꾸면 계속 작업할 수 있고, Opus 4.6이나 Sonnet 4.6의 [1m] 변형 때문이라면 표준 변형으로 바꾸면 됩니다. 세션 한도와 주간 한도는 모든 모델이 함께 쓰므로 모델을 바꿔도 풀리지 않습니다.

클로드 Rate exceeded와 Rate limit reached는 같은 오류인가요?

둘 다 요청이 제한에 걸렸다는 표시지만, Rate exceeded는 Claude.ai, Claude Code, API 중 어디에서 나온 문구인지부터 가려야 확인할 곳이 정해집니다. 경로별 확인 방법은 Claude Rate Exceeded 오류: 재시도 전에 제한 소유자부터 확인하기를 참고하세요.

클로드 529 에러도 같은 방법으로 해결하나요?

아닙니다. API Error: Repeated 529 Overloaded errors는 서비스 전체의 용량이 일시적으로 부족하다는 뜻이고, 내 사용 한도와 관계없으며 할당량에서 차감되지도 않습니다. 몇 분 뒤 다시 시도하거나, 용량이 모델별로 관리되므로 /model로 다른 모델로 바꿔 계속할 수 있습니다. 자세한 판단은 Claude Code 529 과부하 오류: 기다릴지, 모델을 바꿀지와 Claude Code API Error 500·529 해결: 끊긴 작업을 중복 없이 재개하기에 정리돼 있습니다.