SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Claude 사용량 제한 해결 방법: 429 에러와 세션 제한

Claude 세션 제한과 API 429 rate_limit_error의 차이를 설명합니다. 모델군별 제한 확인법과 메시지별 대응 전략을 정리했습니다. 구독 플랜의 사용량 초기화 시점과 API 요청 속도 조절 방법을 확인하여 업무 중단을 최소화하십시오.

Claude의 사용량 제한은 어떻게 되나요?

Claude의 사용량 제한은 두 가지 별도 시스템으로 운영되며, 먼저 어떤 시스템에 의해 제한이 걸렸는지 파악해야 합니다. Claude 구독(Pro, Max, Team 또는 좌석 기반 Enterprise)은 모델군별 상한을 제외하고 모델 간에 공유되는 순환 사용 허용량을 제공하며, 이는 Claude 채팅과도 공유되므로 제한 시 You've hit your session limit · resets 3:45pm와 같은 메시지가 표시됩니다. 현재 사용량 기반 Enterprise 플랜은 예외입니다. 이 플랜은 기본 제공 허용량이 없으며 모든 사용량은 첫 번째 토큰부터 API 요율로 청구됩니다. 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 요청에만 적용되는 구독 제한입니다. Opus 제품군 이외의 모델로 전환하면 작업을 계속할 수 있습니다.
  • You've hit your Sonnet limit · resets 3:45pm은 Sonnet 요청에만 적용되는 동일한 유형의 모델 제품군 제한입니다. Sonnet 제품군 이외의 모델로 전환하면 작업을 계속할 수 있습니다.
  • Fable limit reached로 시작하는 메시지는 Fable 모델에 할당된 주간 허용량을 모두 사용했음을 의미합니다. 계속 진행하면 사용 크레딧이 차감되므로, Claude Code는 먼저 확인을 요청합니다. 플랜 내에서 사용하려면 /model를 사용하여 다른 모델을 선택하십시오.
  • 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 윈도우

Pro, Max, Team 또는 좌석 기반 Enterprise 플랜에는 롤링 방식의 사용량 허용치가 포함되어 있습니다. 이 허용치가 소진되면 Claude Code는 메시지에 표시된 초기화 시간까지 추가 요청을 차단합니다. 이 허용치와 관련하여 혼란을 일으키는 두 가지 특성이 있습니다.

  • Claude 채팅과 공유됩니다. claude.ai에서 수행하는 작업은 터미널 작업과 동일한 허용치에서 차감되므로, 오후에 채팅을 많이 사용하면 저녁에 코딩할 수 있는 시간이 줄어듭니다. 해당 계정으로 로그인한 모든 환경이 동일한 풀을 공유하므로, Linux에서 베타 데스크톱 앱과 Claude Code CLI를 사용하면 각각 하나씩이 아니라 하나의 허용치를 함께 사용하게 됩니다.
  • 모델 간에 공유됩니다. 세션 및 주간 제한은 모든 모델에 대해 하나의 풀로 관리됩니다. 단, 이 풀 내부의 모델군별 상한선은 예외입니다. Opus 및 Sonnet 제한이 이에 해당하며, Max 및 Premium 좌석의 경우 주간 제한의 최대 50%까지 Fable 할당량이 제공됩니다. Pro 및 Standard 좌석의 경우 Fable은 플랜 제한에 포함되지 않으며 첫 요청부터 사용량 크레딧으로 청구됩니다.

Claude for Teams 및 좌석 기반 Enterprise의 경우, 명시된 형태는 5시간 롤링 윈도우와 주간 윈도우를 기준으로 초기화되는 좌석별 허용치이며, 이는 Claude 채팅 및 Cowork과 공유되고 좌석 등급(Standard 또는 Premium)에 따라 크기가 결정됩니다. 현재의 사용량 기반 Enterprise 플랜은 다르게 작동합니다. 소진될 허용치가 포함되어 있지 않으며, 사용량은 API 요금으로 청구되고 상한선은 관리자가 조직 수준 및 개별 사용자별로 설정한 지출 한도에 따릅니다. 영업 지원 플랜의 경우, 지출 한도로 인해 중단된 사용량은 소유자가 한도를 높이지 않는 한 다음 청구 기간이 시작될 때 재개됩니다. 셀프 서비스 플랜의 경우, 선불 크레딧 잔액이 소진되면 소유자가 추가 구매를 할 때까지 사용이 중단됩니다. Pro 및 Max 플랜의 경우, 메시지에 표시된 초기화 시간과 사용자의 /usage 막대가 신뢰할 수 있는 수치이며, 블로그 게시물에서 복사한 수치는 정확하지 않을 수 있습니다. 아직 등급을 선택 중이라면, 필요한 Claude 플랜 확인하기를 통해 각 플랜의 제한 사항을 비교해 보시기 바랍니다.

/model 명령어로 모델을 전환해도 세션이나 주간 제한이 복구되지 않는 이유

이는 가장 흔히 발생하는 오해이며, 문서에서도 명확히 밝히고 있습니다. 세션 및 주간 제한은 모든 모델이 공유하므로 모델을 전환한다고 해서 사용 권한이 복구되지 않습니다. 세션 제한에 도달한 후 더 작은 모델을 선택하면 답변을 생성할 모델만 바뀔 뿐입니다. 세션 및 주간 허용량은 모델별로 관리되지 않으므로, 모델을 전환해도 복구될 잔여량이 존재하지 않습니다.

단, 모델 제품군별 제한은 예외입니다. 메시지에 You've hit your Opus limit 또는 You've hit your Sonnet limit가 표시된다면 /model가 올바른 해결책입니다. 해당 제품군 외의 다른 모델로 전환하여 작업을 계속하십시오. 해당 제품군의 요청만 차단된 상태이기 때문입니다. Max 및 Premium 좌석의 Fable 제한도 동일하게 작동합니다. 다른 모델로 전환하여 플랜 내에서 작업을 계속하거나, 사용 크레딧을 사용하여 Fable을 계속 이용하십시오. 다만 Fable은 다른 모델보다 공유 주간 풀을 더 빠르게 소진하므로, Fable 제한 도달 후 모델을 전환하더라도 전체 주간 제한을 초과하여 사용할 수는 없습니다.

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

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

  1. 초기화 시간을 확인합니다. 세션 윈도우는 짧습니다. 주간 윈도우는 책상 앞에서 기다릴 만한 시간이 아닙니다. Claude Code v2.1.234 이상 버전에서는 /rate-limit-options 명령을 사용하면 초기화를 기다렸다가 중단된 작업을 자동으로 계속할 수 있습니다.
  2. Opus, Sonnet 또는 Fable 한도에 도달했다면 /model 명령을 실행하여 해당 모델군 외의 다른 모델을 선택하십시오.
  3. /usage 명령을 실행하여 플랜 한도, 사용량 막대, 초기화 시점을 확인합니다. /cost은 동일한 화면을 보여주는 별칭입니다.
  4. claude.ai 또는 Claude Desktop의 Settings > Usage에서 Resets 섹션을 확인합니다. 자격이 되는 플랜에는 간혹 무료 한도 초기화 기회가 제공되며, "Reset for free"를 클릭하면 5시간 세션 한도나 주간 한도 중 해당 제안이 적용되는 항목이 즉시 최대로 복구됩니다. 이 버튼은 터미널이나 IDE의 Claude Code 또는 Claude Mobile에서는 사용할 수 없으며, 각 제안에는 만료 기한이 있습니다.
  5. 한도를 초과하여 계속 작업하려면 /usage-credits 명령을 실행하십시오. Pro 및 Max 플랜에서는 결제 설정 페이지가 열립니다. Team 및 Enterprise 플랜에서는 조직의 사용량 설정 페이지가 열리거나, 결제 권한이 없는 경우 관리자에게 요청이 전송됩니다.
  6. 매주 같은 한도에 부딪힌다면 현재 플랜이 작업 방식에 맞지 않는 것이므로, 매번 초기화 때마다 고민하기보다 사용량 한도를 벗어나는 방법을 한 번 검토해 볼 가치가 있습니다.

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

사용량 크레딧에는 미리 알아두어야 할 부작용이 하나 있습니다. 기본적으로 Claude Code는 구독에 포함된 사용량 범위 내에서는 메인 대화에 1시간짜리 프롬프트 캐시를 제공하지만, 크레딧을 사용하기 시작하면 이를 5분으로 단축합니다. 이로 인해 더 많은 턴이 콜드 스타트로 시작되며 동일한 작업이라도 Claude Code 토큰 사용량이 증가하게 됩니다. 서브 에이전트는 메인 대화 버킷 외부에 있으므로 플랜 사용량 범위 내에서도 5분으로 설정됩니다. promptCacheTtl 설정이나 Claude Code v2.1.242 이상 버전의 CLAUDE_CODE_PROMPT_CACHE_TTL 옵션을 사용하여 TTL을 직접 선택하면 크레딧을 사용하는 동안에도 1시간의 수명을 유지할 수 있습니다.

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

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

  • 컨텍스트 또는 자동 압축 경고는 사용량 제한이 아닙니다. /context은 대화가 모델의 컨텍스트 윈도우를 초과하면 Context exceeds the 200k-token limit by 94k tokens와 같은 줄을 출력하고, 이어서 공간을 확보하는 명령어를 표시합니다. 압축은 이전 기록을 요약하여 공간을 확보하지만, 비용이 발생합니다. /compact는 요약할 대화를 읽어 들이므로, 큰 컨텍스트를 압축하는 작업 자체가 플랜에 대해 큰 요청으로 간주됩니다. 연속성 대신 새로운 시작을 원한다면 /clear을 사용하십시오. 비용이 발생하지 않습니다.
  • Prompt is too long · automatic compaction failed: <the underlying error>은 자동 압축 자체가 해당 오류로 인해 실패했음을 의미합니다. /compact은 문제를 해결할 때까지 동일한 오류로 계속 실패합니다.
  • Credit balance is too low는 Console 조직의 선불 크레딧이 소진되었거나, Claude Code가 구독자의 요청을 Console API 키를 통해 전송하고 있음을 의미합니다. /status을 실행하면 현재 활성화된 자격 증명을 확인할 수 있습니다. platform.claude.com/settings/billing에서 크레딧을 충전하십시오. 해당 페이지에서 자동 충전 기능도 제공합니다.
  • API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context은 권한 확인 오류이며, 할당량 소진이 아닙니다. Opus 4.6 또는 Sonnet 4.6의 [1m] 변형을 선택했다면 [1m] 접미사가 없는 변형을 선택하거나 CLAUDE_CODE_DISABLE_1M_CONTEXT=1를 설정하십시오. 대화 도중 컨텍스트가 200K 토큰을 초과하여 이 메시지가 나타나는 경우, Claude Code는 스스로 표준 제한 내로 압축을 수행합니다. Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5 및 Fable 모델은 기본적으로 1M 윈도우로 실행되며 제거해야 할 접미사가 없습니다. 해당 변수는 모델을 200K로 제한하는 역할을 합니다.

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

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

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

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

조직에는 이와는 별개인 지출 한도(spend limit)가 존재하며, 이는 API 사용에 대한 월간 최대 비용을 의미합니다. 계층별 지출 한도에 도달하면 더 높은 한도를 요청하지 않는 한 다음 달까지 API 사용이 중단됩니다. 이 경우에도 429 rate_limit_error 오류가 발생하지만, retry-after 헤더가 없으며 error.details.error_code 내에 enforced_spend_limit_reached 메시지가 포함됩니다. 재시도 루프를 사용해도 이 문제는 해결되지 않습니다. 콘솔에서 직접 설정한 낮은 지출 한도에 도달하면 다르게 동작합니다. 요청 시 HTTP 400 invalid_request_error 오류가 반환되며 You have reached your specified API usage limits로 시작하는 메시지가 표시됩니다. 한도를 높이거나 제거하면 다시 접근할 수 있습니다.

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으로 명명된 계층은 실제 수치를 결정하며, 사용 이력과 계정 상태에 따라 자동으로 할당됩니다. 신규 조직이나 사용 이력이 적은 조직은 표준 게시 제한보다 낮은 Evaluation 계층에서 시작할 수 있으므로, 예상보다 일찍 첫 429 오류가 발생할 수 있습니다. 사용량이 급격히 증가하면 가속 제한이 작동하여 계층 내 허용 범위 안에서도 429 오류가 발생할 수 있으므로 트래픽을 점진적으로 늘려야 합니다. 게시된 모든 수치는 상한선입니다. 문서화된 제한은 허용되는 최대 사용량이며, 보장된 최소 사용량이 아닙니다. 한도 상향을 요청하려면 Claude 콘솔의 Rate limits 페이지에서 "Request tier 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은 요청을 재시도하기 전까지 대기해야 하는 시간(초)입니다. 이 시간 이전에 재시도하면 실패합니다. 모든 429 오류에 이 헤더가 포함되지는 않으며, spend-cap 429 오류에는 절대 포함되지 않습니다.
  • anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining 및 anthropic-ratelimit-requests-reset은 요청 예산을 설명합니다.
  • anthropic-ratelimit-input-tokens-* 및 anthropic-ratelimit-output-tokens-*은 ITPM과 OTPM에 대해 동일한 정보를 제공하며, limit, remaining, reset 접미사를 사용합니다.
  • anthropic-ratelimit-tokens-*는 현재 적용 중인 가장 엄격한 제한 값을 표시합니다.

Reset 헤더는 RFC 3339 타임스탬프 형식입니다. Remaining 토큰 헤더는 가장 가까운 천 단위로 반올림되므로, 이를 게이지(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의 사용량 페이지에 "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"

이 작업에는 관리자 API 자격 증명이 필요합니다. 관리자 API 키, org:admin 범위가 포함된 OAuth 토큰, 또는 작업 공간(workspace)에 한정되지 않은 개인용 또는 서비스 계정 키가 필요합니다. 작업 공간 API 키는 작동하지 않습니다. GET /v1/organizations/workspaces/{workspace_id}/rate_limits은 작업 공간별로 동일한 작업을 수행합니다. 두 명령 모두 읽기 전용입니다. 제한을 변경하려면 Console의 Rate 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는 무료 티어를 제공하지 않기 때문입니다. Max 및 Team 플랜에는 Console 조직을 연결한 후 자체 앱과 에이전트를 실행할 수 있는 월간 API 크레딧이 포함되어 있습니다. 해당 크레딧은 Claude Code에는 적용되지 않으며 플랜의 사용량 제한을 변경하지 않습니다. VPS에서 첫 Claude API 앱 실행하기에서 키 관리 및 재시도 로직을 다루며, tmux 내부에서 Claude Code를 실행하면 연결이 끊겨도 에이전트의 긴 작업이 중단되지 않고 유지됩니다.

FAQ

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

세션 및 주간 제한은 모든 모델에서 공유되기 때문입니다. 해당 허용량은 특정 모델이 아닌 플랜에 귀속되므로, /model을 통해 모델을 변경하더라도 남은 허용량에는 변화가 없습니다. 예외적으로 모델 제품군별 제한이 존재합니다. You've hit your Opus limit 및 You've hit your Sonnet limit은 해당 제품군에만 적용되며, Max 및 Premium 좌석의 Fable 제한은 Fable 모델에만 적용됩니다. 이 경우에는 모델을 변경하는 것이 문서화된 해결 방법입니다.

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

해당 모델 등급에 대한 속도 제한(분당 요청 수, 분당 입력 토큰 수, 분당 출력 토큰 수)에 도달했음을 의미합니다. 응답에는 일반적으로 대기해야 할 시간(초)을 나타내는 retry-after 헤더가 포함되며, 이 시간 이전에 재시도하면 실패합니다. 공식 SDK는 속도 제한 및 5xx 오류 발생 시 지수 백오프(exponential backoff)를 사용하여 기본적으로 2회 재시도하며, 해당 헤더가 존재할 경우 이를 준수합니다. 사용 중인 티어의 제한 범위 내에 있음에도 429 오류가 발생한다면, 이는 급격한 요청 증가로 인한 가속 제한(acceleration limit) 때문일 수 있습니다. error.details.error_code에 enforced_spend_limit_reached가 포함된 429 오류는 월간 지출 한도에 도달했음을 의미하며, retry-after 헤더가 포함되지 않으므로 잠시 기다려도 해결되지 않습니다.

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

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

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

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

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