SSD Nodes Learn
가이드 Matt Connor작성자 Matt Connor · 업데이트됨 2026-07-24

Claude 사용 제한 해결 방법: 구독 및 API 차이점

Claude 구독의 session 제한과 API의 HTTP 429 rate limit은 해결 방법이 다릅니다. 모델 변경 여부와 함께 각 오류 메시지별 대응 방안을 확인하십시오.

Claude의 사용 제한은 무엇입니까?

Claude의 사용 제한은 두 가지 별개의 시스템으로 운영됩니다. 먼저 어떤 시스템에 의해 제한되었는지 확인해야 합니다. Claude 구독(Pro, Max, Team 또는 Enterprise)은 모델 간에 공유되는 유동적 사용 허용량을 제공하며, Claude chat과 공유됩니다. 이 경우 You've hit your session limit · resets 3:45pm와 같은 메시지가 표시되며 사용이 중단됩니다. Claude API는 다른 기준을 사용합니다. 분당 요청 및 token 전송 속도를 측정합니다. 이 경우 rate_limit_error 유형의 HTTP 429 오류가 발생하며, retry-after 헤더에 대기해야 할 초 단위 시간이 표시됩니다.

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

요금제별 허용량과 rate-limit tier 번호는 자주 변경됩니다. 잘못된 수치를 제공하는 것은 아무 정보도 없는 것보다 해롭기 때문에 여기에는 수치를 기재하지 않습니다. 아래의 명령어를 사용하여 직접 확인하십시오.

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

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 rate limit입니다. API key, Amazon Bedrock 또는 Google Cloud 프로젝트에 설정된 제한에 도달했습니다.
  • API Error: Server is temporarily limiting requests (not your usage limit)는 플랜 할당량과 무관한 일시적인 throttle입니다. Claude Code는 해당 메시지를 표시하기 전, backoff 방식을 사용하여 자동으로 재시도합니다.

구독 제한 사항: session, weekly, 그리고 Opus window

구독 플랜에는 rolling usage allowance가 포함됩니다. 이 할당량이 소진되면, 메시지에 표시된 reset time까지 Claude Code의 추가 요청이 차단됩니다. 할당량의 다음 두 가지 특성 때문에 혼동이 자주 발생합니다.

  • Claude chat과 할당량을 공유합니다. claude.ai에서 수행한 작업은 terminal에서의 작업과 동일한 할당량을 사용합니다. 따라서 chat에서 많은 작업을 수행하면 저녁 시간의 코딩 작업 시간이 단축됩니다.
  • 모델 간에 할당량을 공유합니다. Opus limit를 제외하고, session 및 weekly limit에는 모델별 예산이 설정되어 있지 않습니다.

Claude for Teams 및 Enterprise의 경우, 문서에 명시된 구조는 seat tier(Standard 또는 Premium)에 따라 크기가 결정되는 per-seat allowance입니다. 이 할당량은 rolling five-hour window 및 weekly window에 따라 reset되며, Claude chat 및 Cowork과 공유됩니다. Pro 및 Max의 경우, 블로그 포스트의 수치가 아닌 메시지에 출력된 reset time과 사용자의 /usage bar가 신뢰할 수 있는 수치입니다. 아직 플랜을 선택 중이라면, 필요한 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 key 인증 방식으로는 사용할 수 없습니다. API key에는 확장 가능한 플랜 할당량이 없기 때문입니다.

사용 크레딧(Usage credits)에는 반드시 알아두어야 할 부작용이 있습니다. 구독 상태에서 프롬프트 캐시(prompt cache) 유지 시간은 1시간이지만, 크레딧을 사용하기 시작하면 5분으로 단축됩니다. 따라서 동일한 작업을 수행하더라도 더 많은 턴(turn)이 발생하며 Claude Code token usage가 증가합니다.

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

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

  • context 또는 auto-compact 경고는 사용량 제한이 아닙니다. 대화 내용이 모델의 context window를 초과하면 /context에 Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.와 같은 메시지가 출력됩니다. 공간을 확보하기 위해 이전 대화 기록이 요약되며, 사용자의 plan allowance에는 영향을 주지 않습니다.
  • Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.은 /compact 자체가 실패했음을 의미합니다. 요약본을 생성할 만큼 충분한 free context가 남아있지 않기 때문입니다.
  • Credit balance is too low은 Console organization의 선불 크레딧이 모두 소진되었음을 의미합니다. platform.claude.com/settings/billing에서 크레딧을 충전하십시오. 해당 페이지에서 auto-reload 설정도 가능합니다.
  • API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context은 권한 확인(entitlement check)이며, 할당량(quota) 소진이 아닙니다. [1m] 접미사가 없는 모델 변형을 선택하거나 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하십시오.

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

API rate limits: 429 오류의 실제 산정 기준

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

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

조직에는 별도의 지출 한도(spend limit)가 설정되어 있습니다. 이는 API 사용에 대한 월간 최대 비용을 의미합니다. 해당 티어의 지출 한도에 도달하면, 한도 상향을 요청하지 않는 한 다음 달까지 API 사용이 중단됩니다. 재시도 루프(retry loop)로는 이 문제를 해결할 수 없습니다.

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

  • 한도는 모델 클래스별로 적용됩니다. 각 모델에 개별적으로 적용되므로, 각 모델의 한도 내에서 여러 모델을 동시에 사용할 수 있습니다. 일부 모델군은 한도를 공유합니다. Opus 계열의 한도는 Claude Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5의 합계로 적용되며, Claude Sonnet 5는 별도의 한도를 가집니다.
  • 용량은 지속적으로 충전됩니다. API는 token bucket 알고리즘을 사용하므로, 특정 시점에 초기화되는 대신 용량이 지속적으로 보충됩니다. 분당 60회 요청 한도가 초당 1회 요청으로 강제될 수 있습니다. 따라서 60개의 요청을 동시에 보내면 여전히 실패합니다.
  • 대부분의 모델에서 캐시되지 않은 입력만 ITPM에 포함됩니다. input_tokens 및 cache_creation_input_tokens은 포함됩니다. 대부분의 Claude 모델에서 cache_read_input_tokens는 포함되지 않으나, Claude Haiku 3.5는 문서에 명시된 예외 사항입니다. 따라서 캐싱을 사용하면 비용 절감뿐만 아니라 rate limit 여유 공간을 확보할 수 있습니다. 출력의 경우, 높은 max_tokens은 OTPM에 영향을 주지 않습니다. OTPM은 실제로 생성된 토큰만 계산하기 때문입니다.
  • 한도는 조직(organization) 수준에서 관리됩니다. 워크스페이스(workspace)에 더 낮은 한도를 설정할 수 있으며, 워크스페이스 한도의 합계가 높더라도 조직 전체 한도가 우선 적용됩니다. 워크스페이스에서 한도를 별도로 설정하지 않으면 무제한이 되는 것이 아니라 조직의 한도를 상속받습니다.

Start, Build, Scale, Custom으로 명명된 티어(Tier)가 실제 수치를 결정하며, 이는 사용 이력과 계정 상태에 따라 자동으로 할당됩니다. 신규 조직은 공개된 표준 한도보다 낮은 수치에서 시작할 수 있으므로, 첫 429 오류가 표에 명시된 것보다 일찍 발생할 수 있습니다. 사용량이 급증하면 가속 제한(acceleration limits)이 트리거됩니다. 이 경우 해당 티어 범위 내에 있더라도 429 오류가 반환되므로, 트래픽을 점진적으로 늘려야 합니다. 모든 공개 수치는 상한선입니다. 문서에 명시된 한도는 허용되는 최대 사용량이며, 보장된 최소 사용량이 아닙니다. 한도 상향이 필요한 경우 Claude Console의 Limits 페이지에 있는 "Request rate limit increase" 컨트롤을 사용하십시오.

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

모든 API 오류는 동일한 구조를 반환합니다. 유형과 메시지를 포함하는 중첩된 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-*는 현재 적용 중인 가장 엄격한 제한 값을 표시합니다.

Reset 헤더는 RFC 3339 타임스탬프 형식입니다. Remaining 토큰 헤더는 천 단위로 반올림되므로 지표(gauge)로 간주하고 읽어야 합니다. Fast mode는 별도의 풀(pool)과 별도의 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으로 나타납니다. 기술 지원팀에 문의할 때 이 값을 인용하십시오.

Backoff 루프를 구현하기 전에 실제로 필요한지 먼저 확인하십시오. 공식 SDK는 연결 오류, 속도 제한(rate limits), 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가 일시적으로 과부하 상태임을 의미하며, 모든 사용자의 트래픽이 급증할 때 발생할 수 있습니다. 사용자의 API key나 코드의 문제는 아닙니다. SDK가 5xx 응답에 대해 이미 수행하고 있는 exponential backoff 방식을 사용하여 재시도하십시오. 문제가 지속되면 status.claude.com을 확인하십시오. 500 api_error 에러는 내부 에러이며 동일한 방식으로 재시도해야 합니다. 두 에러 모두 rate limit(요청 제한)이 아닙니다.

표 대신 직접 한도 확인하기

구독 서비스에서는 /usage 화면이 가장 중요합니다. 이 화면은 플랜 사용량 막대와 상세 내역을 보여줍니다. d 또는 w를 사용하여 지난 24시간과 지난 7일 사이의 데이터를 전환할 수 있습니다. 주의 사항이 두 가지 있습니다. Session 블록은 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 key가 필요하며, GET /v1/organizations/workspaces/{workspace_id}/rate_limits는 워크스페이스별로 동일한 작업을 수행합니다. 두 방식 모두 읽기 전용입니다. 한도를 변경하려면 Console의 Limits 탭을 사용하십시오.

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

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

  • 턴당 토큰 사용량을 줄입니다. 작업을 지속하면 cache가 유지됩니다. 관련 없는 작업 사이의 /clear는 비용이 발생하지 않습니다. Claude Code 토큰 사용량에서 해당 내용에 대해 자세히 설명합니다.
  • 작업 강도를 낮춥니다. 단계는 low, medium, high, xhigh, max입니다. /effort 메뉴에는 사용량을 늘리는 ultracode 옵션도 있습니다. 단순한 이름 변경 작업에 deep reasoning을 사용할 필요는 없습니다.
  • 429 오류 발생 시 동시 실행 수를 줄입니다. CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY를 낮추고 다수의 병렬 subagents 사용을 피하십시오. /status도 확인하십시오. 잘못된 ANTHROPIC_API_KEY는 요청을 구독 계정이 아닌 low-tier key로 전달합니다.
  • 비대화형 작업은 Message Batches API로 옮깁니다. 이 API는 대량의 작업을 비동기로 처리하며, 입력 및 출력 토큰 비용을 50% 할인합니다. 자체적인 rate limits를 사용하므로 야간 작업이 현재 세션과 충돌하지 않습니다.

사람이 아닌 프로그램에 의해 발생하는 간헐적인 작업은 처음부터 API key를 사용하는 것이 적합합니다. VPS에서 처음으로 Claude API 앱 구축하기에서 key 관리 및 재시도 방법을 다룹니다. 또한 tmux 내부 VPS에서 Claude Code 실행하기를 사용하면 연결이 끊겨도 장시간 실행되는 agent 작업을 유지할 수 있습니다.

FAQ

왜 모델을 변경해도 Claude 사용량 제한이 해결되지 않습니까?

세션 및 주간 제한은 모든 모델에 공유되기 때문입니다. 할당량은 모델이 아닌 요금제에 귀속됩니다. 따라서 /model은 응답 모델을 변경할 뿐 남은 할당량을 변경하지 않습니다. 유일한 예외는 You've hit your Opus limit이며, 이는 Opus 요청에만 적용됩니다. 이 경우 모델을 변경하는 것이 공식적인 해결 방법입니다.

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

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

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

Claude Code에서 /usage를 실행하면 요금제 한도, 초기화 시간 및 사용량 세부 정보를 확인할 수 있습니다. /cost은 별칭(alias)이며, d 또는 w를 사용하여 최근 24시간과 최근 7일 사이를 전환할 수 있습니다. 이 수치는 로컬 세션 기록을 기반으로 하므로 다른 기기나 claude.ai에서의 사용량은 포함되지 않습니다. API의 경우, Console에서 속도 제한을 확인할 수 있으며, Admin API key를 사용하면 GET /v1/organizations/rate_limits을 통해 설정된 제한 값을 반환받을 수 있습니다.

Claude 요금제 한도에 도달한 후에도 작업을 계속할 수 있습니까?

경우에 따라 가능합니다. Pro 및 Max 요금제에서 한도 이상의 사용량을 구매하려면 /usage-credits을 실행하십시오. Team 및 Enterprise 요금제에서는 관리자에게 요청하십시오. 이를 위해서는 /login을 통한 claude.ai 로그인이 필요하며, API key 인증으로는 사용할 수 없습니다. 그렇지 않은 경우 초기화 시간까지 대기하거나, Opus 제한인 경우 모델을 변경하십시오. 또는 윈도우 단위가 아닌 분당 단위로 측정되는 API key로 작업을 전환하십시오.

#claude#claude-code#ai#rate-limits#api