Claude Code가 50% 표시인데 주간 한도 경고가 발생하는 원인과 해결법
Claude Code 세션 표시기에 여유가 있음에도 주간 사용 한도 경고가 발생할 때의 대처법: 카운터 차이점, 안전한 컨텍스트 저장 및 API 연동 방안 정리.
목차
Claude Code에 50%가 표시되는데 주간 사용 한도 경고나 중단 메시지가 나올 수 있습니다. 두 값이 같은 카운터를 가리킨다고 볼 수는 없습니다. 표시와 경고의 라벨을 확인하지 않은 채 “절반이 남았다”고 판단하면 작업 중간에 멈출 수 있습니다.
먼저 경고의 정확한 문구, 로그인 방식, 다음 초기화 시각을 기록하세요. 그다음 커밋되지 않은 작업을 안전하게 보관하고, 구독 사용량과 API 사용량을 별도의 경로로 다뤄야 합니다.
50% 표시와 한도 경고는 서로 다른 지표일 수 있습니다
Claude Code에서 보이는 숫자와 경고는 최소한 다음처럼 구분할 수 있습니다.
| 표시 또는 경고 | 확인할 내용 | 그 값만으로 알 수 없는 내용 |
|---|---|---|
| context 표시 | 현재 대화와 로드된 정보가 context window에서 차지하는 비율 | 플랜 사용량이 얼마나 남았는지 |
| 5시간 사용 경고 | 현재 세션에서 플랜에 포함된 사용량 | 주간 한도나 context 여유 |
| 주간 사용 한도 | 플랜에 배정된 주간 사용량과 다음 초기화 시각 | 현재 대화가 짧은지 여부 |
| API 사용량 | API Key로 실행한 요청의 청구, 사용량, 적용되는 제한 | Claude 웹 구독의 남은 사용량 |
Anthropic의 현재 안내는 5시간 사용량과 주간 한도를 context length와 별도로 설명합니다. 적용되는 한도, 초기화 방식, usage credits 사용 가능 여부는 플랜과 계정에 따라 달라질 수 있습니다. 다른 글이나 스크린샷을 보고 고정 토큰 수, 고정 초기화 주기, 추가 사용 가능 여부를 추정하지 마세요.
웹 구독과 별도로 API를 통해 Claude Code를 구성하려면 BetterToken의 Claude Code 가이드에서 현재 연결 방법을 확인할 수 있습니다. BetterToken API 접근은 자신의 계정과 API Key를 사용합니다. 이는 Claude 웹 구독 한도를 늘리는 방법이 아니라 별도의 API 사용 경로입니다.
먼저 경고 문구와 초기화 시간을 확인합니다
경고가 나온 직후 같은 prompt를 반복해서 보내지 마세요. 다음 순서로 확인합니다.
- 터미널에 표시된 메시지를 그대로 기록합니다.
Approaching 5-hour limit, 주간 한도,limit reached, resets at …,429는 같은 원인을 뜻하지 않을 수 있습니다. - Claude 계정에서 현재 플랜과 Usage 화면의 다음 초기화 시간을 확인합니다. 5시간 한도와 주간 한도가 따로 보인다면 어느 쪽이 먼저 소진됐는지 기록합니다.
- API Key로 Claude Code를 실행하고 있을 가능성이 있다면 환경 변수와 설정을 확인합니다. API Key 실행은 구독 로그인과 같은 청구·한도 경로가 아닙니다.
/context,/compact,/clear는 context를 다루는 데 도움이 되지만 구독 사용량을 초기화하는 명령은 아닙니다.
429는 짧은 시간의 rate limit, 업스트림 혼잡, API 쪽 인증·잔액·제한 등에서도 발생할 수 있습니다. 메시지 문구, HTTP status, 실행에 사용한 인증 경로를 구분한 뒤 대응하세요.
작업을 멈출 시점과 안전한 handoff 절차
한도 도달이나 초기화 대기가 표시되고 다음 변경이 크다면, 억지로 계속하지 말고 작업 상태를 넘깁니다. 안전한 checkpoint에서 내용을 보지 않고 모든 파일을 stage하지 않는 것이 중요합니다.
git status --short
git diff --check
git switch -c checkpoint/usage-limit
git add -p
git commit -m "checkpoint: save state before usage reset"그다음 HANDOFF.md 또는 작업 관리 도구에 다음을 남깁니다.
- 완료한 변경과 아직 검증하지 않은 변경
- 다음에 실행할 테스트 또는 확인 명령
- 수정한 파일과 건드리면 안 되는 파일
- 표시된 한도 메시지, 인증 경로, 알고 있는 초기화 시각
백그라운드 retry나 오래 실행되는 작업이 있다면 상태를 확인한 뒤 중지합니다. 새 세션에서 다시 시작할 때는 handoff를 읽고, 먼저 짧은 확인부터 수행합니다.
구독 사용량과 API 사용량을 혼동하지 마세요
Claude 웹 구독과 API Key 실행은 인증, 청구, 사용량을 확인하는 위치가 다릅니다.
| 구분 | 웹 구독 | API Key 실행 |
|---|---|---|
| 인증 | Claude 계정 로그인 | 선택한 API provider의 Key |
| 사용 조건 | 플랜, 계정, 기능별 사용량 제한 | API provider의 청구와 적용되는 rate·잔액 조건 |
| 확인 위치 | Claude Usage 화면과 경고 메시지 | API provider의 usage·청구·요청 기록 |
| 서로의 영향 | API에 충전해도 웹 플랜 한도가 자동으로 바뀌지 않음 | 웹 플랜 초기화가 API 사용 조건을 바꾸지 않음 |
API를 사용하더라도 무제한 실행, 특정 속도, 특정 성공률을 전제로 하지 마세요. 현재 Model ID, 사용 가능 여부, 가격, rate 조건은 선택한 provider의 최신 정보로 확인합니다.
재개 전에 작은 범위로 검증합니다
사용량이 초기화되었거나 다른 인증 경로로 전환한 뒤 곧바로 큰 refactor를 다시 시작할 필요는 없습니다.
/model또는 대상 도구 설정에서 의도한 인증 경로와 모델을 확인합니다.- handoff에 적어 둔 최소 확인 명령이나 작은 read-only 작업을 실행합니다.
- 예상한 응답이 돌아오는지, Usage 화면 또는 API 사용 기록에서 어떤 경로가 사용됐는지 확인합니다.
- 그 후 남은 작업을 재개하고, 긴 작업은 의미 있는 checkpoint 단위로 나눕니다.
이 순서를 따르면 context 부족, 5시간 한도, 주간 한도, API 쪽 문제를 모두 하나의 “사용 한도”로 취급하지 않게 됩니다.
자주 하는 오해
50%라면 주간 한도도 50% 남아 있다.
표시 대상이 다르므로 그렇게 판단할 수 없습니다. 라벨과 Usage 화면을 확인하세요.
새 대화를 시작하면 주간 한도가 돌아온다.
새 대화는 context를 정리하는 데 도움이 될 수 있지만, 플랜 사용량을 초기화하지는 않습니다.
API 잔액을 충전하면 Claude 웹 제한이 해제된다.
인증과 청구 경로가 다릅니다. 전환하기 전에 Claude Code가 어느 경로로 실행 중인지 확인하세요.
429는 반드시 주간 한도 때문이다.
429에는 다른 원인도 있습니다. 오류 문구, 초기화 정보, 인증 경로를 함께 확인해야 합니다.
