Claude 사용량 제한 해결 방법 및 오류 코드 확인

Claude의 사용량 제한은 어떻게 됩니까?

Claude의 사용량 제한은 두 가지 별도의 시스템으로 나뉩니다. 첫 번째 작업은 어떤 시스템 때문에 제한이 걸렸는지 파악하는 것입니다. Claude 구독(Pro, Max, Team 또는 Enterprise)은 모델 간에 공유되고 Claude 채팅과도 공유되는 순환식 사용 허용량을 제공하며, 제한에 도달하면 You've hit your session limit · resets 3:45pm와 같은 메시지가 표시됩니다. Claude API는 다른 기준, 즉 분당 요청 및 토큰 전송 속도를 측정합니다. 이 제한에 도달하면 rate_limit_error 유형의 HTTP 429 오류가 발생하며, retry-after 헤더를 통해 대기해야 할 초 단위 시간이 안내됩니다.

두 제한의 해결 방법은 서로 다릅니다. 구독 제한은 특정 기간 내 사용량에 관한 것이므로, 초기화될 때까지 기다리거나 추가 사용량을 구매해야 합니다. API 속도 제한은 현재 전송 속도에 관한 것이므로, 전송 속도를 늦추면 몇 초 내에 해제됩니다.

플랜별 허용량과 속도 제한 등급 수치는 자주 변경됩니다. 잘못된 수치를 기재하는 것은 아예 기재하지 않는 것보다 못하므로, 여기에는 수치를 명시하지 않습니다. 아래의 명령어를 사용하여 본인의 제한 수치를 직접 확인하십시오.

어떤 제한에 도달했습니까? 정확한 메시지를 확인하십시오

Claude Code는 출력되는 텍스트에 시스템 이름을 명시합니다. 설정을 변경하기 전에 본인의 상황과 일치하는지 확인하십시오.

• You've hit your session limit · resets 3:45pm은 구독 제한입니다. 해당 기간 동안의 플랜별 사용 허용량을 모두 소진했습니다.
• You've hit your weekly limit · resets Mon 12:00am은 더 긴 기간을 기준으로 하는 동일한 시스템의 제한입니다.
• You've hit your Opus limit · resets 3:45pm는 Opus 요청에만 적용되는 구독 제한입니다. 이 경우에만 모델을 전환하는 것이 도움이 됩니다.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.은 API 속도 제한입니다. API 키, Amazon Bedrock 또는 Google Cloud 프로젝트에 설정된 제한에 도달했습니다. Bedrock이나 Vertex 클라이언트는 Anthropic 조직이 아닌 클라우드 프로젝트의 할당량을 기준으로 측정되므로, 클라이언트 인증 방식에 따라 적용되는 제한이 달라집니다.
• API Error: Server is temporarily limiting requests (not your usage limit)은 플랜 할당량과는 무관한 일시적인 스로틀링입니다. Claude Code는 해당 메시지를 표시하기 전에 자동으로 백오프(backoff)를 적용하여 재시도를 수행합니다.

구독 제한: 세션, 주간, 그리고 Opus 윈도우

구독 플랜에는 롤링 방식의 사용량 한도가 포함되어 있습니다. 한도를 모두 소진하면 Claude Code는 메시지에 표시된 초기화 시간까지 추가 요청을 차단합니다. 이 한도와 관련하여 혼동을 일으키는 두 가지 특성이 있습니다.

• Claude 채팅과 공유됩니다. claude.ai에서 수행하는 작업은 터미널 작업과 동일한 한도에서 차감되므로, 오후에 채팅을 많이 사용하면 저녁에 코딩할 수 있는 시간이 줄어듭니다. 해당 계정으로 로그인한 모든 환경이 동일한 풀을 공유하므로, Linux에서 베타 데스크톱 앱과 Claude Code CLI를 사용하면 각각 하나씩이 아니라 합쳐서 하나의 한도를 소모합니다.
• 모델 간에 공유됩니다. 세션 및 주간 한도는 모델별 예산을 따로 두지 않으며, Opus 한도만이 유일한 예외입니다.

Claude for Teams 및 Enterprise의 경우, 명시된 구조는 5시간 롤링 윈도우와 주간 윈도우를 기준으로 초기화되는 좌석별 한도입니다. 이 한도는 Claude 채팅 및 Cowork과 공유되며, 좌석 등급(Standard 또는 Premium)에 따라 크기가 결정됩니다. Pro 및 Max 플랜의 경우, 블로그 게시물에 적힌 수치가 아니라 메시지에 출력되는 초기화 시간과 사용자의 /usage 막대 그래프가 가장 정확한 지표입니다. 아직 플랜을 선택 중이라면 필요한 Claude 플랜 확인하기를 통해 각 플랜의 제한 사항을 비교해 보시기 바랍니다.

/model 명령어로 모델을 전환해도 접근 권한이 복구되지 않는 이유

이는 가장 흔히 발생하는 잘못된 조치이며, 문서에서도 이에 대해 명확히 밝히고 있습니다. 세션 제한과 주간 제한은 모든 모델에서 공유되므로 모델을 전환한다고 해서 접근 권한이 복구되지 않습니다. 세션 한도가 소진된 후 더 작은 모델을 선택하면 답변을 생성할 모델만 바뀔 뿐입니다. 허용량은 모델별로 책정되는 것이 아니므로, 모델을 전환해도 새로 확보되는 허용량은 없습니다.

예외적으로 Opus 제한은 모델별로 적용되는 고유한 상한선입니다. 메시지에 You've hit your Opus limit이 표시된다면 /model가 올바른 해결책입니다. Opus 요청만 차단된 상태이므로 다른 모델로 전환하여 작업을 계속하십시오.

제한을 버그로 간주하는 것 또한 잘못된 대응입니다. 재설치나 재인증을 수행해도 아무것도 바뀌지 않습니다. 허용량은 세션 기간이 초기화되거나 사용 크레딧을 구매할 때 복구됩니다.

구독 한도에 도달했을 때의 대처 방법

1. 초기화 시간을 확인하십시오. 세션 윈도우는 짧습니다. 주간 윈도우는 책상 앞에서 기다릴 만한 시간이 아닙니다.
2. Opus 한도에 도달했다면 /model를 실행하여 다른 모델을 선택하십시오.
3. /usage을 실행하여 플랜 한도, 사용량 막대, 초기화 시점을 확인하십시오. /cost은 동일한 화면으로 연결되는 별칭입니다.
4. 한도를 초과하여 계속 작업하려면 /usage-credits을 실행하십시오. Pro 및 Max 플랜에서는 결제 설정이 열립니다. Team 및 Enterprise 플랜에서는 조직의 사용량 설정이 열리거나, 결제 권한이 없는 경우 관리자에게 요청이 전송됩니다.
5. 매주 동일한 한도에 부딪힌다면 현재 플랜이 작업 방식에 맞지 않는 것입니다. 매번 초기화 시점에 고민하기보다 사용량 한도를 벗어나는 방법을 한 번 검토해 보는 것이 좋습니다.

/usage-credits를 사용하려면 /login을 통해 로그인한 claude.ai 구독이 필요합니다. API 키 인증으로는 사용할 수 없는데, 이는 API 키에는 확장 가능한 플랜 허용량이 없기 때문입니다.

사용량 크레딧에는 미리 알아두어야 할 부작용이 하나 있습니다. 프롬프트 캐시 유지 시간은 구독 상태일 때는 1시간이지만, 크레딧을 사용하기 시작하면 5분으로 줄어듭니다. 따라서 더 많은 턴이 콜드 상태에서 시작되며, 동일한 작업이라도 Claude Code 토큰 사용량이 증가하게 됩니다.

사용량 제한처럼 보이지만 실제로는 그렇지 않은 메시지

Claude Code에서 발생하는 4가지 오류는 사용량 제한으로 보고되지만, 실제로는 사용량 제한이 아닙니다.

• 컨텍스트 또는 자동 압축 경고는 사용량 제한이 아닙니다. 대화 내용이 모델의 컨텍스트 윈도우를 초과하면 /context이 Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.와 같은 줄을 출력합니다. 이전 기록은 공간 확보를 위해 요약되며, 사용자의 플랜 허용량은 차감되지 않습니다.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.은 /compact 자체가 실패했음을 의미합니다. 요약 결과물을 담을 수 있는 충분한 컨텍스트 공간이 남아있지 않기 때문입니다.
• Credit balance is too low는 Console 조직의 선불 크레딧이 소진되었음을 의미합니다. platform.claude.com/settings/billing에서 크레딧을 추가하십시오. 해당 페이지에서 자동 충전 기능도 제공합니다.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context은 할당량 소진이 아니라 권한 확인 오류입니다. [1m] 접미사가 없는 모델 버전을 선택하거나 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하십시오.

API에서 발생하는 오류가 하나 더 있습니다. 413 request_too_large는 단일 요청에 대한 크기 제한이며, 속도 제한(rate limit)이 아닙니다.

API 속도 제한: 429 오류가 실제로 집계하는 항목

Messages API는 모델 클래스별로 다음 세 가지 항목을 개별적으로 측정합니다.

• 분당 요청 수 (RPM)
• 분당 입력 토큰 수 (ITPM)
• 분당 출력 토큰 수 (OTPM)

조직에는 이와는 별개인 지출 한도(spend limit)가 존재하며, 이는 API 사용에 대한 월간 최대 비용을 의미합니다. 계층별 지출 한도에 도달하면 더 높은 한도를 요청하지 않는 한 다음 달까지 API 사용이 중단됩니다. 이 문제는 재시도 루프로 해결할 수 없습니다.

429 오류가 발생하는 시점은 다음 네 가지 메커니즘에 의해 결정됩니다.

• 제한은 모델 클래스별로 적용됩니다. 각 모델에 개별적으로 적용되므로, 서로 다른 모델을 각자의 한도 내에서 동시에 사용할 수 있습니다. 일부 제품군은 버킷을 공유합니다. 예를 들어 Opus 속도 제한은 Claude Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5 전체에 걸친 총합이며, Claude Sonnet 5는 별도의 제한을 가집니다.
• 용량은 지속적으로 충전됩니다. API는 토큰 버킷 알고리즘을 사용하므로, 특정 시점에 초기화되는 것이 아니라 지속적으로 용량이 보충됩니다. 분당 60회 요청 제한은 초당 1회 요청으로 강제될 수 있으므로, 60회 요청을 한꺼번에 보내면 실패하게 됩니다.
• 대부분의 모델에서 캐시되지 않은 입력만 ITPM에 집계됩니다. input_tokens 및 cache_creation_input_tokens은 집계 대상입니다. 대부분의 Claude 모델에서 cache_read_input_tokens는 집계되지 않으며, Claude Haiku 3.5가 문서화된 예외입니다. 따라서 캐싱은 비용 절감뿐만 아니라 속도 제한의 여유 공간을 확보해 줍니다. 출력 측면에서 높은 max_tokens은 OTPM에 집계되지 않는데, 이는 OTPM이 실제로 생성된 토큰만을 계산하기 때문입니다.
• 제한은 조직 수준에서 적용됩니다. 워크스페이스에 더 낮은 제한을 설정할 수 있으며, 워크스페이스 제한의 합계가 더 크더라도 조직 전체 제한이 항상 우선 적용됩니다. 워크스페이스에서 재정의하지 않은 제한은 무제한이 아니라 조직으로부터 상속받은 값을 따릅니다.

Start, Build, Scale, Custom으로 명명된 계층이 실제 수치를 결정하며, 이는 사용 이력과 계정 상태에 따라 자동으로 할당됩니다. 신규 조직은 표준 게시 제한보다 낮은 상태로 시작할 수 있으므로, 예상보다 일찍 첫 429 오류가 발생할 수 있습니다. 급격한 사용량 증가는 가속 제한을 유발하여 계층 내 사용량 범위 안에서도 429 오류를 반환할 수 있으므로, 트래픽을 점진적으로 늘려야 합니다. 모든 게시된 수치는 상한선입니다. 문서화된 제한은 허용되는 최대 사용량이지 보장된 최소 사용량이 아닙니다. 한도 증액을 요청하려면 Claude Console의 Limits 페이지에 있는 "Request rate limit increase" 제어 항목을 사용하십시오.

429 오류 읽기: retry-after, 헤더 및 SDK 재시도

모든 API 오류는 동일한 봉투(envelope) 형태로 반환됩니다. 여기에는 유형과 메시지를 담은 중첩된 error 객체와 최상위 수준의 request_id가 포함됩니다.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

나머지 정보는 헤더에 담겨 있습니다.

• retry-after은 요청을 재시도하기 전까지 대기해야 하는 초 단위 시간입니다. 이보다 일찍 재시도하면 실패합니다.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining 및 anthropic-ratelimit-requests-reset는 요청 예산(request budget)을 설명합니다.
• anthropic-ratelimit-input-tokens-* 및 anthropic-ratelimit-output-tokens-*은 ITPM과 OTPM에 대해 동일한 작업을 수행하며, limit, remaining, reset 접미사를 동일하게 사용합니다.
• anthropic-ratelimit-tokens-*는 현재 적용 중인 가장 제한적인 한도 값을 표시합니다.

리셋 헤더는 RFC 3339 타임스탬프 형식입니다. 남은 토큰 헤더는 가장 가까운 천 단위로 반올림되므로, 이를 게이지(gauge)로 읽어야 합니다. Fast 모드는 별도의 풀과 자체 anthropic-fast-* 헤더를 가집니다. 성공한 모든 호출에서 이 헤더들을 읽으십시오.

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

모든 응답에는 req_018EeWyXxfu5pfWkrYcMdjWG와 같은 고유한 request-id 헤더가 포함됩니다. 이는 오류 본문에서는 request_id으로, Python 및 TypeScript SDK 응답에서는 _request_id로 나타납니다. 고객 지원팀에 문의할 때 이 값을 인용하십시오.

백오프 루프를 작성하기 전에 실제로 필요한지 먼저 확인하십시오. 공식 SDK는 연결 오류, 속도 제한, 5xx 서버 오류를 포함한 일시적인 실패를 자동으로 재시도합니다. 이때 지수 백오프(exponential backoff)를 사용하며 기본적으로 2회 재시도하고, retry-after 헤더가 존재하면 이를 준수합니다. 각 클라이언트는 이 동작을 변경하거나 비활성화할 수 있는 maximum-retries 옵션을 지원합니다.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error는 사용자의 잘못이 아닙니다

429 오류는 요청 속도가 너무 빠를 때 발생합니다. 529 overloaded_error 오류는 API가 일시적으로 과부하 상태임을 의미하며, 모든 사용자에게서 발생하는 높은 트래픽으로 인해 나타날 수 있습니다. 사용자의 키나 코드에는 아무런 문제가 없습니다. SDK는 이미 5xx 응답에 대해 지수 백오프(exponential backoff)를 수행하므로 이를 사용하여 재시도하십시오. 문제가 해결되지 않으면 status.claude.com에서 상태를 확인하십시오. 500 api_error 오류는 내부 오류이며 동일한 방식으로 재시도하면 됩니다. 두 오류 모두 속도 제한(rate limit)과는 무관합니다.

표 대신 직접 제한 사항 확인하기

구독 중이라면 /usage 화면이 중요합니다. 이 화면에는 요금제 사용량 막대와 사용량 상세 내역이 표시되며, d 또는 w을 눌러 최근 24시간과 최근 7일 간의 데이터를 전환할 수 있습니다. 두 가지 주의 사항이 있습니다. 세션 블록은 API 토큰 사용량을 보여주며 API 사용자를 위한 것이므로, 구독자는 여기에 표시된 금액을 무시해도 됩니다. 이 수치는 해당 기기의 로컬 세션 기록에서 가져온 것이므로, 다른 기기나 claude.ai에서 발생한 사용량은 포함되지 않습니다.

API 측면에서는 Claude Console의 Usage 페이지에 "Rate Limit - Input Tokens"와 "Rate Limit - Output Tokens"라는 두 개의 차트가 표시됩니다. 입력 차트는 현재 ITPM 제한 대비 분당 캐시되지 않은 입력 토큰의 시간당 최대치를 캐시 비율과 함께 보여줍니다. 이를 통해 운영 환경에서 제한에 도달하기 전에 미리 제한 임계값에 가까워지는지 모니터링할 수 있습니다.

설정된 제한 사항을 프로그래밍 방식으로 확인하려면 다음을 사용하십시오.

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

이 작업에는 Admin API 키가 필요하며, GET /v1/organizations/workspaces/{workspace_id}/rate_limits는 워크스페이스별로 동일한 정보를 제공합니다. 두 방식 모두 읽기 전용입니다. 제한을 변경하려면 Console의 Limits 탭을 사용하십시오.

less를 사용하여 제한 사항을 줄이는 방법

두 시스템 모두 내부적으로 동일한 항목을 측정하므로, 다음 방법들은 두 시스템 모두에 적용됩니다.

• 턴당 토큰 사용량을 줄입니다. 연속적인 작업은 캐시를 유지하며, 관련 없는 작업 사이의 /clear는 비용이 발생하지 않습니다. Claude Code 토큰 사용량에서 해당 방법을 상세히 다룹니다.
• 작업 강도를 낮춥니다. 레벨은 low, medium, high, xhigh, max가 있습니다. /effort 메뉴에서 제공하는 ultracode는 비용을 낮추는 대신 높입니다. 단순한 기계적 이름 변경에 깊은 추론을 사용하는 것은 비효율적입니다.
• 429 오류 발생 시 동시성을 줄입니다. CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY을 낮추고 다수의 병렬 하위 에이전트 실행을 피하십시오. 또한 /status를 실행하십시오. 잘못된 ANTHROPIC_API_KEY 설정은 요청을 구독 계정이 아닌 하위 티어 키로 라우팅할 수 있습니다.
• 비대화형 작업은 Message Batches API로 전환합니다. 이 API는 대량의 작업을 비동기적으로 처리하며 입력 및 출력 토큰에 대해 50% 할인 혜택을 제공합니다. 자체적인 속도 제한을 따르므로 야간 작업이 현재 세션과 자원을 두고 경쟁하지 않게 됩니다.

컨텍스트에 데이터를 대량으로 입력하는 작업에서 이러한 제한이 가장 크게 느껴집니다. 실시간 시장 데이터로 주식 및 옵션을 분석할 때, 전체 시세표나 체인 데이터를 붙여넣는 대신 질문에 필요한 좁은 범위의 데이터만 추출하면 비용을 크게 절감할 수 있습니다. 사람이 아닌 프로그램이 주도하는 일시적인 작업은 처음부터 API 키를 사용하는 것이 좋습니다. API로 전환하면 측정 방식뿐만 아니라 결제 방식도 변경됩니다. Claude API는 가입 시 제공되는 소액의 크레딧 외에는 무료 티어를 제공하지 않기 때문입니다. VPS에서 첫 번째 Claude API 앱 실행하기에서는 키 관리 및 재시도 로직을 다루며, tmux 내부의 VPS에서 Claude Code를 실행하면 연결이 끊겨도 에이전트 작업을 지속할 수 있습니다.

FAQ

모델을 변경해도 Claude 사용량 제한이 해결되지 않는 이유는 무엇입니까?

세션 및 주간 제한은 모든 모델 간에 공유되기 때문입니다. 사용량 허용 범위는 특정 모델이 아닌 플랜에 귀속되므로, /model을 변경하는 것은 답변할 모델을 바꿀 뿐 남은 허용량을 늘려주지 않습니다. 단, Opus 요청에만 적용되는 You've hit your Opus limit은 예외입니다. 이 경우에는 모델을 변경하는 것이 문서화된 해결 방법입니다.

429 rate_limit_error는 무엇을 의미하며 얼마나 기다려야 합니까?

해당 계정이 모델 클래스별 속도 제한(분당 요청 수, 분당 입력 토큰 수, 분당 출력 토큰 수)에 도달했음을 의미합니다. 응답에는 대기해야 할 초 단위를 나타내는 retry-after 헤더가 포함되어 있으며, 이보다 일찍 재시도하면 실패합니다. 공식 SDK는 이미 해당 헤더를 준수하며 지수 백오프(exponential backoff)를 통해 속도 제한 및 5xx 오류를 기본적으로 2회 재시도합니다. 계정의 티어 제한 내에 있음에도 429 오류가 발생한다면, 갑작스러운 요청 급증으로 인한 가속 제한(acceleration limit)이 원인일 수 있습니다.

Claude 사용량 제한과 초기화 시점은 어떻게 확인합니까?

Claude Code에서 /usage를 실행하면 플랜 사용량 막대, 초기화 시간, 사용량 상세 내역을 확인할 수 있습니다. /cost은 동일한 기능을 수행하는 별칭이며, d 또는 w를 사용하면 최근 24시간과 최근 7일 간의 기록을 전환하여 볼 수 있습니다. 해당 수치는 로컬 세션 기록을 기반으로 하므로 다른 기기나 claude.ai에서의 사용량은 포함되지 않습니다. API의 경우, 콘솔에서 속도 제한 차트를 확인할 수 있으며, 관리자 API 키를 사용하면 GET /v1/organizations/rate_limits을 통해 설정된 제한을 조회할 수 있습니다.

Claude 플랜 제한에 도달한 후에도 계속 작업할 수 있습니까?

경우에 따라 가능합니다. /usage-credits를 실행하여 Pro 및 Max 플랜의 경우 제한을 초과하는 사용량을 구매하거나, Team 및 Enterprise 플랜의 경우 관리자에게 요청할 수 있습니다. 이 과정은 /login를 통한 claude.ai 로그인이 필요하며, API 키 인증 방식으로는 사용할 수 없습니다. 그 외에는 초기화 시간까지 기다리거나, Opus 제한인 경우 모델을 변경하거나, 작업 환경을 API 키 기반으로 전환하십시오. API 키는 윈도우 단위가 아닌 분 단위로 사용량을 측정합니다.