Claude Code 속도 제한: 구독 한도와 API 429 구분하기

Claude Code에서 rate limit이 의미하는 것

Claude Code에는 근본적으로 다른 두 인증 모드가 있습니다.

• 구독(Pro, Max, Team, Enterprise): Claude.ai OAuth로 로그인합니다. Claude Code와 다른 Claude 표면은 플랜의 공유 풀을 사용하므로 현재 창과 추가 제한은 /usage 및 계정 설정에서 확인합니다.
• API 키(환경의 ANTHROPIC_API_KEY): 요청이 api.anthropic.com으로 직접 전송됩니다. 제한은 Anthropic Console의 워크스페이스 tier에 따른 RPM, ITPM, OTPM입니다.

ANTHROPIC_API_KEY가 설정되어 있으면 구독보다 우선합니다. 구독으로 로그인했더라도 Claude Code가 API 키로 전환할 수 있으므로 흔한 혼동 원인입니다.

요청이 타사 엔드포인트에 도달했는지 알아야 하나요? BetterToken은 추가 진단 계층을 제공합니다. Dashboard에서 요청 상태, 모델, input/output/cache Token 및 해당 청구를 확인할 수 있어 공급자 제한과 Anthropic API 오류를 구분하는 데 도움이 됩니다. Base URL과 API 키 설정은 BetterToken 문서에서 확인하고 현재 workflow와 대조하세요.

구독, Anthropic API 또는 다른 엔드포인트의 제한 식별하기

먼저 Claude Code에서 /status를 실행하세요. 현재 인증이 구독 계정인지 API 키인지 표시하며, 그 결과가 다음 조사 위치를 정합니다.

• Pro/Max/Team 구독: /status가 subscription을 보이고 메시지에 session 또는 weekly limit과 재설정 시간이 있으면 플랜 사용량이 소진된 것입니다. 재설정을 기다리고 /usage, 가능하면 /usage-credits를 확인하세요.
• Anthropic API 429: /status가 API 키를 보이고 ANTHROPIC_API_KEY가 환경에 있으며 응답에 HTTP 429 또는 rate_limit_error가 있으면, 선택 tier의 RPM, ITPM 또는 OTPM이 제한된 것입니다. 먼저 retry-after를 확인하고 동시성을 줄이세요.
• 타사 엔드포인트: 사용자 지정 Base URL과 공급자 키를 사용하면 코드와 응답 형식이 Anthropic과 다를 수 있습니다. 응답을 먼저 읽고 공급자의 status page와 쿼터 조건을 확인하세요.

500 api_error, 504 timeout_error, 529 overloaded_error는 별도로 처리합니다. 이는 서버 측 또는 일시적 오류이지 구독 할당량 소진의 증거가 아닙니다. 제한된 exponential backoff를 사용하세요. Anthropic 응답에는 헤더의 request-id가, 오류 JSON에는 request_id도 포함되므로 지원 문의용으로 저장합니다.

API 키를 노출하지 않는 단계별 진단

1단계. 인증 방법 확인

Claude Code 세션에서 실행합니다.

/status

“Login method” 또는 “Auth token”을 봅니다. ANTHROPIC_API_KEY가 있지만 구독을 사용하려면 먼저 변수를 제거하세요.

unset ANTHROPIC_API_KEY

Claude Code를 다시 시작하고 /status를 재확인합니다.

2단계. 전체 오류 메시지 읽기

정확한 문구가 핵심 진단 신호입니다. Resets at [시간]은 구독 제한이므로 재설정을 기다립니다. retry-after 헤더가 있는 rate_limit_error는 API 429이므로 Anthropic Console을 확인합니다. api_error, timeout_error, overloaded_error는 backoff로 재시도할 일시적 5xx/529 오류입니다. 비표준 Base URL과 공급자 고유 형식은 공급자 측 문제를 가리킵니다.

시간, error.type, request-id/request_id, Claude Code 버전, 선택한 엔드포인트를 안전한 진단 정보로 저장하세요. API 키, Authorization 헤더, .env 내용은 포함하지 마세요.

3단계. 현재 사용량 확인

구독의 경우:

/usage

Pro/Max usage bar에서 5시간 창 재설정 전 잔여량과 주간 상한 전 잔여량을 확인합니다. /model로 모델을 바꿔도 이미 소비한 compute 시간은 복구되지 않으며, 할당량은 모델 간에 공유됩니다.

API는 Anthropic Console → Settings → Limits에서 tier, 현재 RPM/ITPM/OTPM 제한, 사용량을 확인하세요. BetterToken에서는 Dashboard를 열어 시간으로 요청을 찾습니다. 모델, 상태, input/output/cache Token, 청구를 볼 수 있습니다. Dashboard는 요청이 BetterToken에 도달했는지 보여 주지만, 응답 본문이나 헤더의 식별자는 별도로 보관하세요.

4단계. 공식 상태 확인

https://status.anthropic.com/

Claude Code 또는 API에 영향을 주는 인시던트는 본인의 제한과 별개로 문제를 설명할 수 있습니다.

5단계. 구성 충돌 확인

ANTHROPIC_API_KEY와 ANTHROPIC_BASE_URL을 함께 설정하면 예상치 못한 동작이 발생할 수 있습니다. 하나의 환경에 서로 다른 인증 방식용 변수 세트를 두 개 유지하지 마세요. 도움을 요청할 때도 로그나 스크린샷에 Authorization, x-api-key, .env 내용을 포함하지 마세요. 오류 텍스트, HTTP 코드, claude --version, 키 값을 제거한 /status면 충분합니다.

원인을 확인한 뒤 할 일

구독 제한(Pro/Max/Team): /usage와 오류 메시지가 표시하는 재설정을 기다리세요. 특정 모델 제한이면 /model로 사용 가능한 모델을 선택할 수 있지만 전체 플랜 사용량은 재설정되지 않습니다. usage credits가 있으면 /usage-credits와 설정을 확인하고, 관련 없는 작업 사이에는 /clear로 컨텍스트를 초기화해 이후 요청의 소비를 줄이세요.

Anthropic API 429(rate_limit_error): 응답의 retry-after를 읽고 해당 시간만큼 기다립니다. 병렬 에이전트 작업은 RPM, ITPM, OTPM을 더 빨리 소모하므로 동시성을 줄입니다. 오래된 고정 수치 대신 Anthropic Console → Settings → Limits에서 현재 tier와 제한을 확인하세요. 지속적으로 더 큰 한도가 필요하면 Console을 통해 Anthropic에 증액을 요청하세요.

타사 엔드포인트: 공급자의 status page를 열고 현재 쿼터와 오류 형식을 확인한 뒤, 필요하면 직접 Anthropic API 또는 다른 공급자로 전환하세요.

5xx / 529: 500, 504, 529에는 제한된 exponential backoff를 사용합니다. 공식 SDK는 일부 일시적 오류를 이미 재시도합니다. status.anthropic.com을 확인하고 오류가 계속되면 비밀 정보 없이 request-id, 시간, 오류 유형을 지원팀에 전달하세요.

언제 기다리고, 부하를 바꾸고, 지원팀에 연락할까

• 재설정 시간이 있는 구독 제한: 기다리거나, 모델을 바꾸거나, /clear를 사용합니다.
• retry-after가 있는 API 429: 지정 시간만큼 기다리고 동시성을 줄입니다.
• retry-after 없는 빈번한 API 429: tier를 확인하고 필요하면 상향을 요청합니다.
• 500 / 504 / 529: 제한된 exponential backoff, 서비스 상태 확인, request-id 보관을 합니다.
• 타사 엔드포인트 오류: 해당 공급자에 연락합니다.
• 활성 구독인데 불분명한 제한: Claude.ai 지원팀에 연락합니다.
• 활성 API 키인데 불분명한 제한: Anthropic Console 지원팀에 연락합니다.

구독 지원과 API 지원은 별도 팀입니다. Anthropic API Console 팀은 Pro/Max 구독 제한을 해결할 수 없으며 그 반대도 마찬가지입니다.

FAQ

세션을 막 시작했는데 왜 “rate limit”이 보이나요?

(1) 낮은 tier의 ANTHROPIC_API_KEY가 환경에 있고 구독보다 우선하는 경우(/status로 확인), (2) 이전 세션이 롤링 창의 상당 부분을 사용했으며 Claude Code 재시작으로 재설정되지 않는 경우, (3) 여러 기기나 에이전트 작업이 같은 계정을 사용해 사용량이 합산되는 경우가 있습니다.

/model로 모델을 바꾸면 도움이 되나요?

구독에서는 일부 도움이 됩니다. You've hit your Opus limit은 Opus 할당량이 소진되었다는 뜻이며 Sonnet으로 바꾸면 같은 세션을 계속할 수 있습니다. 하지만 공유되는 주간 및 5시간 compute budget은 모델 변경으로 복구되지 않습니다.

도움을 요청할 때 전체 로그를 포함해야 하나요?

아니요. 전체 오류 텍스트, HTTP 코드, 키 값을 뺀 /status, claude --version, 발생 시각, 당시 status.anthropic.com 상태면 충분합니다.

가장 자주 바뀌는 동적 제한은 무엇인가요?

API tier 제한(RPM, ITPM, OTPM)과 구독 창 매개변수는 바뀔 수 있습니다. 현재 값은 공식 페이지에서만 확인하세요.

• 비용 및 사용량: code.claude.com/docs/en/costs
• API 오류 및 속도 제한: platform.claude.com/docs/en/api/errors
• 서비스 상태: status.anthropic.com

튜토리얼이나 포럼의 수치는 빠르게 오래되므로 신뢰하지 마세요.