대시보드의 사용량이 절반도 안 되는데 Claude Code 가 사용량 제한에 걸리는 상황을 추적한 기록이다. 구독(Pro · Max)과 API 종량제는 제한 체계가 완전히 다르므로 두 가지를 섞어 놓고 원인을 찾으면 계속 빗나간다.
| 구분 | 구독 (Pro · Max) | API 종량제 |
|---|---|---|
| 제한 단위 | 5시간 세션 창, 주간 상한 | 분당 요청 수(RPM), 분당 토큰 수(TPM) |
| 리셋 | 세션은 롤링, 주간은 세션 시작 후 7일 | 매 분 |
| 확인 | 계정 설정의 Usage 화면, CLI 의 /status |
응답 헤더의 anthropic-ratelimit-* |
구독 사용자에게는 분당 제한이 적용되지 않는다. RPM · TPM 이야기가 나오면 API 문서를 구독에 잘못 대입한 것이다.
구독 쪽 제한은 둘이고 둘 중 하나만 걸려도 차단된다.
또 하나 놓치기 쉬운 것은 여러 제품 표면이 같은 몫을 쓴다는 점이다. 웹 · 데스크톱 앱 · 터미널의 Claude Code 사용량이 한 계정 안에서 합산된다. 오전에 웹에서 오래 쓰면 오후 코딩 세션의 여유가 줄어든다.
한 번의 명령이 한 번의 호출이 아니다. 시스템 프롬프트, 누적 대화, 컨텍스트에 들어간 파일 내용, 파일 읽기 · 셸 실행 · 검색 같은 도구 호출이 모두 입력 토큰에 얹힌다. 세션이 길어질수록 매 요청에 히스토리 전체가 다시 실려 토큰이 가파르게 늘어난다.
제한은 시간이 아니라 토큰으로 추적된다. 코드베이스 전체를 10분 만에 훑으면, 한 시간 동안 짧은 질문을 하는 것보다 훨씬 빨리 소진된다.
claude # 실행 후 세션 안에서
/status # 세션 · 주간 · 모델별 사용량
계정 설정의 Usage 화면과 CLI 의 값이 다르면 그 불일치 자체가 이상 신호다.
환경변수에 API 키가 있으면 Claude Code 는 구독 대신 그 키로 인증하고, 그 순간부터 API 요금이 청구된다. 사용량이 남았는데 제한에 걸린다고 느끼는 원인이 여기인 경우가 있다.
echo "$ANTHROPIC_API_KEY"
unset ANTHROPIC_API_KEY
cat ~/.claude/.credentials.json
구독 종류와 등급 필드가 비어 있으면 인증 정보가 제대로 잡히지 않은 것이다. 로그아웃 후 다시 로그인한다.
claude logout
claude login
IDE 확장과 CLI 는 같은 자격증명을 쓰지만 확장 쪽에서만 값이 초기화되는 사례가 보고돼 있다. 한쪽에서만 재현되는지 갈라 본다.
| 방법 | 효과 |
|---|---|
세션 안에서 /compact |
누적 대화를 요약해 이후 요청의 입력 토큰을 줄인다 |
| 새 세션 시작 | 히스토리를 끊는다. 긴 세션이 가장 큰 소비원이다 |
| 가벼운 모델로 전환 | 특정 모델의 주간 상한에 걸렸을 때 특히 효과가 있다 |
| 무시 목록 설정 | 빌드 산출물 · 의존성 디렉터리가 컨텍스트에 딸려 들어가지 않게 한다 |
| 웹 사용 줄이기 | 같은 몫을 나눠 쓴다 |
구독 약관에는 "용량 관리와 공정한 접근을 위해 주간 · 월간 상한이나 모델 · 기능 단위 제한 등 다른 방식으로 사용량을 제한할 수 있다" 는 재량 조항이 들어 있다. 즉 화면에 표시되는 세 가지(세션 · 주간 전체 · 주간 모델별) 외의 제한이 존재할 수 있고, 그 내용은 공개되지 않는다.
혼잡 시간대에 세션 몫이 더 빨리 소진되도록 조정한 사례가 실제로 있었다. 다만 그 가중치가 대시보드 수치에 반영되는지 여부는 어느 공식 문서에도 적혀 있지 않다 (확인 필요). 반영된다고도 안 된다고도 단정하지 않는다.
정리하면 세션 · 주간 · 모델별이 모두 여유 있는데 제한에 걸린다면 남는 후보는 셋이다 — 비공개 재량 제한, 인증 · 자격증명 문제, 서비스 측 일시 장애. 앞의 두 가지를 먼저 배제하고 남으면 서비스 상태 페이지를 확인한 뒤 문의한다.