Claude Code 비용·한도 길잡이: 구독 한도와 API 요금 줄이는 법

한창 작업하는데 Claude Code가 한도에 걸렸다며 멈췄습니다. 이럴 때 모델부터 바꿔 보고 싶어지는데, 그게 듣는 경우와 안 듣는 경우가 갈려요. 메시지가 세션·주간 한도인지 모델 계열 한도인지부터 보세요.

세션·주간 한도는 모든 모델이 함께 쓰는 거라 모델을 바꿔도 안 풀리고, 리셋 시각까지 기다려야 합니다. You've hit your Opus limit 같은 모델 계열 한도나 529 과부하라면 다른 모델로 바꿔서 계속 쓸 수 있고요.

다음부터 덜 막히고 싶다면 제가 제일 먼저 권하는 건 컨텍스트 줄이기예요. 구독 한도와 API 요금 양쪽에 다 듣는 방법이거든요.

이 글은 한도·요금 관련 글을 쓰면서 정리해 둔 지도입니다.

줄이는 방법이 어디에 듣는지는 2026년 9월 21일에 Claude Code 비용·오류 문서와 API 가격 페이지를 대조해 정리했고, 지시 파일 크기가 요청마다 실리는 토큰을 얼마나 늘리는지는 10월 17일 Windows 11 테스트 환경에서 직접 재 봤습니다.

금액은 자주 바뀌어서 적지 않았어요. 확인일이 붙은 수치는 링크한 글과 공식 가격 페이지에 있습니다.

상황별로 먼저 열 글

작업 도중 한도 메시지가 뜨거나 월말 청구서를 보고 놀랐다면, 찾는 답은 대개 아래 중 하나에 있습니다.

• 한도 메시지가 떴는데 무엇이 막힌 건지 모르겠다 → 529·사용량 제한 오류를 메시지 문구별로 가른 글
• 남은 한도와 리셋 시각을 보고 싶다 → /usage 화면 읽는 법과 5시간·주간 한도
• Codex를 ChatGPT 계정으로 쓴다 → Codex 5시간·주간 한도의 남은 양과 리셋 시각 보는 법
• 같은 작업을 토큰을 덜 쓰고 하고 싶다 → 토큰 절약 방법 8가지를 전후로 직접 잰 결과
• 컨텍스트가 찼다는 경고가 뜬다 → /compact와 /clear를 언제 쓰는지
• 작업에 맞는 싼 모델을 고르고 싶다 → Claude Code 모델 바꾸는 법과 작업별 선택
• 캐싱을 켰는데 금액이 안 줄었다 → 프롬프트 캐싱이 실제로 비용을 줄이는 조건 네 가지

막혔을 때 보는 순서

저는 아래 순서대로 봅니다. 순서를 뒤집으면 듣지도 않는 방법에 시간을 쓰게 돼요.

1. 컨텍스트 경고인가, 한도인가

화면이 컨텍스트나 자동 압축을 말하고 있다면 한도가 아닙니다. 대화가 자동 압축 임계에 가까워졌다는 뜻이라, 기다려도 안 풀려요.

/compact나 /clear로 대화를 정리하세요. 반대로 한도라면 대화를 정리해도 안 풀립니다.

2. 어느 한도인가

메시지에 세션·주간·모델 계열 중 무엇인지 나옵니다. 세션·주간 한도면 모델을 바꿔도 소용없고, 모델 계열 한도면 다른 계열 모델로 바꿔 계속 쓰면 됩니다.

529는 사용 한도가 아니라 전체 이용자에 걸친 용량 문제라 할당량에서 차감되지 않아요. 용량이 모델별로 추적되니 이때도 모델을 바꾸면 도움이 됩니다.

3. 지금 풀까, 다음부터 줄일까

막힌 순간에 할 수 있는 건 사실상 모델 전환(듣는 경우에만)과 리셋 시각까지 기다리기뿐입니다. 컨텍스트 정리나 캐싱은 이미 깎인 창을 되돌려 주지 않고, 다음 요청부터 효과가 나요.

구독 중인데 한도는 그대로이고 청구서만 늘어난다면 얘기가 다릅니다. 환경에 API 키가 남아 있으면 요청이 구독이 아니라 그 키로 나갈 수 있거든요.

활성 자격 증명부터 확인하세요. 확인하는 순서는 한도·과부하 오류 글의 429 항목에 있습니다.

구독과 API는 막히는 방식이 다르다

구독이든 API든 세는 단위는 요청 횟수가 아니라 토큰입니다. 그런데 막히는 방식이 달라요. 구독은 시간 창에 막히고, API는 쓴 만큼 청구됩니다.

쓰는 방식	무엇이 쌓이나	언제 풀리나	막혔다는 신호
구독	시간 창 안의 토큰	메시지의 리셋 시각	You've hit your session limit · resets 3:45pm
API	토큰 × 종류별 단가	풀리지 않음	청구 금액, Request rejected (429)

구독은 세션 창과 주간 창이 번갈아 차는 게 아니라 동시에 찹니다. 한 번에 크게 돌리면 세션 창은 리셋돼도 주간 창은 줄어든 채로 남아요.

그래서 급하지 않은 일은 나눠 돌리는 편이 주간 창을 지키는 데 낫습니다.

병렬로 도는 서브에이전트도 각자 컨텍스트를 갖고 토큰을 쓴다는 것도 기억해 두세요.

API는 한 모델에 단가가 여러 개입니다. 입력과 출력이 다르고, 캐시에 쓸 때와 읽을 때가 또 달라요. 같은 문장도 모델마다 토큰 수가 다르게 세어지니, 모델끼리 비교할 때는 단가보다 토큰 수부터 맞추세요.

어느 쪽이 싼지는 한 달에 쓰는 토큰 양에 따라 달라서, 한쪽이 항상 싸지는 않습니다. 구독 중이면 창 사용률부터, API를 쓰고 있으면 청구서의 토큰 항목부터 보세요. 두 숫자를 어디서 보는지는 사용량 확인 글에 있습니다.

하나만 줄인다면 컨텍스트

줄이는 방법마다 듣는 곳이 다릅니다. 표로 놓고 보면 세 칸 모두에 듣는 건 컨텍스트 줄이기뿐이에요.

방법	구독 시간 창	모델 계열 한도	API 요금
모델 바꾸기	듣지 않음	들음	단가만 바뀜
컨텍스트 줄이기	들음	들음	들음
동시 실행 줄이기	들음	들음	총량 같으면 그대로
프롬프트 캐싱	확인되지 않음	확인되지 않음	조건 네 개 충족 시 들음
기다리기	리셋 시각에 풀림	리셋 시각에 풀림	듣지 않음

컨텍스트 줄이기는 매 요청이 다시 싣는 양 자체를 줄입니다. 큰 로그를 통째로 넘기지 않기, 읽을 파일을 지정하기 같은 방법별 효과는 토큰 절약 실측 글에 있어요.

“매 요청이 다시 싣는다”가 얼마나 되는지 10월 17일 Windows 11 · Claude Code 2.1.296에서 재 봤습니다. 빈 폴더와, 규칙 120줄짜리 CLAUDE.md(21.6KB)를 둔 폴더에서 claude -p "Reply with exactly: ok" --model haiku --output-format json을 두 번씩 보내고 usage의 입력 토큰을 더했어요.

폴더	첫 호출 입력	두 번째 호출 입력
빈 폴더	26,335	26,335
CLAUDE.md 21.6KB	33,060	33,060

“ok” 한 마디를 받는 데도 요청마다 6,725토큰이 더 실렸습니다. 두 번째 호출은 캐시에서 읽혀 API 단가는 낮아지지만, 실리는 양 자체는 그대로였어요. 지시 파일을 짧게 두면 매 요청에서 이만큼이 빠집니다.

프롬프트 캐싱은 API 요금에서만 효과가 확인됐습니다.

조건을 못 맞추면 오류 없이 정가로 청구되니, 켰다는 것만으로는 아무것도 확인이 안 돼요. 응답의 사용량 필드를 봐야 합니다.

구독 한도에 캐시 적중이 어떻게 반영되는지는 근거를 찾지 못해서 표에 “확인되지 않음”으로 두었습니다.

동시 실행을 줄여도 청구서는 그대로예요. 순서대로 하든 동시에 하든 토큰 총량이 같으면 금액도 같습니다. 효과는 짧은 시간에 몰린 요청이 부딪히는 시간 창과 요청 한도 쪽에서 나요.

마치며

세션·주간 한도에 걸렸다면 모델을 바꿔 봐야 헛수고입니다. 그래서 저는 메시지 한 줄을 끝까지 읽는 게 제일 빠른 해결이라고 생각해요. 그리고 길게 보면 결국 컨텍스트를 덜 싣는 습관이 구독이든 API든 가장 크게 남습니다.

지금 Claude Code를 쓰고 있다면 /usage를 열어 세션 창과 주간 창이 각각 얼마나 찼는지부터 확인해 보세요. 화면의 숫자가 각각 무엇인지는 Claude Code 사용량 확인법에 정리해 뒀습니다.