Claude Code가 API Error: Rate limit reached를 표시하면 먼저 제한의 owner를 찾아야 합니다. 인증 경로, 현재 usage/reset 화면, API key 또는 cloud provider 제한, 컨텍스트 증가, 도구 재시도, 오탐 상태를 분리해야 정확한 복구가 가능합니다.
빠른 답
- Claude 계정 또는 Enterprise로 로그인했다면 현재 계정/조직의 usage/reset 화면을 기준으로 판단합니다.
- API key를 사용한다면
/cost를 실행하고 Claude Console, Bedrock, Vertex, Microsoft Foundry의 현재 limit, spend,retry-after를 확인합니다. - 큰 작업이라면
/compact,/clear, 좁은 파일 범위,/model에 표시되는 더 가벼운 route로 압박을 줄입니다. - 보이는 사용량과 오류가 맞지 않으면 credential을 새로 고치고 세션을 다시 시작한 뒤 증거를 모아 escalate합니다.
제한 owner 확인
Claude Code의 제한은 세 가지 표면에서 올 수 있습니다. Claude 계정/Enterprise 사용량 창, API key나 cloud provider의 rate/spend limit, 또는 로컬 세션 상태입니다.
bash/model /cost claude --version
/model은 오늘 계정에서 실제로 사용 가능한 model route를 보여줍니다. /cost는 API billing 경로에서 의미가 있습니다. 오래된 시간표, 가격표, 다른 계정의 스크린샷을 현재 계약처럼 사용하지 마세요.
즉시 복구
가능하면 더 가벼운 route로 전환하세요. 포맷팅, 짧은 수정, 문법 질문, 요약은 가장 무거운 route가 필요하지 않습니다. 고위험 다중 파일 변경과 설계 판단에는 더 강한 route를 남겨두세요.
컨텍스트를 정리하세요. 작업이 끝났으면 /clear를 사용합니다. 긴 대화를 유지해야 하면 /compact를 먼저 실행합니다. 다른 작업을 오래된 같은 세션에서 계속 이어가지 않는 것이 중요합니다.
파일 범위를 좁히세요. 전체 저장소 대신 관련 디렉터리와 파일을 지정합니다. 파일 읽기, 검색, 로그, 테스트 출력은 이후 호출의 context가 됩니다.
retry-after를 따르세요. API나 cloud provider route에서는 headers와 dashboard가 오래된 블로그 숫자보다 신뢰할 수 있습니다.
짧은 세션도 제한될 수 있는 이유
Claude chat은 보통 직접적인 질문-응답에 가깝습니다. Claude Code는 파일을 읽고, 검색하고, 명령을 실행하고, 변경을 쓰고, 테스트를 돌리는 agentic tool system입니다. 하나의 보이는 요청이 여러 tool step과 model call을 만들 수 있습니다.
중요한 질문은 사용 시간이 아니라 세션이 만든 context와 tool output입니다. 큰 CLAUDE.md, 넓은 검색, 긴 로그, 반복 실패, subagents, 오래된 thread 계속 사용은 이후 호출을 무겁게 만듭니다.
사용량 줄이기
CLAUDE.md는 짧고 안정적으로 유지하세요. 현재 Anthropic route가 prompt caching의 이점을 받더라도 숫자 기반 용량 계획은 최신 문서에서 확인한 뒤 세워야 합니다.
관련 질문은 하나의 구조화된 prompt로 묶으세요. 작은 질문을 여러 번 던지면 같은 context를 반복 전송합니다.
긴 설명은 로컬 파일로 저장하고 다음에는 그 파일을 참조하세요. 같은 코드를 매번 다시 분석하게 만들지 마세요.
작업 위험도에 따라 route를 선택하세요. 낮은 위험 작업은 가벼운 route, 높은 위험 변경은 더 강한 route를 사용합니다. 사용 가능 여부는 /model로 확인합니다.
오탐과 escalate
usage 화면과 오류가 맞지 않으면 CLI version, auth route, /model, API session의 /cost, usage/reset screen, exact error, timestamp를 기록합니다. logout/login과 fresh session을 시도한 뒤 현재 issue tracker나 support에 전달하세요.
reset을 기다리는 동안
테스트 작성, 로그 축소, 다음 작업 분할, clean context packet 준비, PR 리뷰, 문서 업데이트처럼 blocked route가 없어도 가능한 일을 진행하세요. 다른 coding tool을 임시로 쓴다면 현재 quota, model route, data policy, billing을 먼저 확인하세요.
FAQ
언제 제한이 회복되나요?
owner에 따라 다릅니다. Claude Code/계정의 reset, API headers, Console, provider dashboard, Enterprise 설정을 확인하세요.
업그레이드해야 하나요?
context cleanup, model routing, 오탐 배제를 했는데도 실제 작업이 반복적으로 막힐 때만 평가하세요. 오늘 계정의 가격, 대기 비용, API 또는 Enterprise route와 비교해야 합니다.
왜 chat보다 더 빨리 압박이 생기나요?
Claude Code는 tool calls를 실행하기 때문입니다. file reads, searches, commands, writes, tests가 context와 calls를 늘립니다. chat은 보통 더 직접적인 request-response입니다.