# Claude Rate Exceeded 오류: 재시도 전에 제한 소유자부터 확인하기

> Claude API Error: Rate limit reached가 곧 한도 소진은 아닙니다. 최신 Claude Code 메시지로 플랜, 1M 권한, API 키, 게이트웨이 중 막힌 곳을 찾으세요.

- URL: https://blog.laozhang.ai/ko/posts/claude-rate-exceeded-error
- Published: 2026-05-09
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude·Anthropic
- Tags: Claude, Rate Limit, Claude Code, Anthropic API

---
`Claude API Error: Rate limit reached`, "Rate Exceeded", Claude Code의 429 중 무엇을 봤든 남은 사용량이 바닥났다고 바로 단정하지 마세요. 같은 문구 뒤에 플랜 사용 한도, 1M 컨텍스트 사용 권한, API 키 워크스페이스의 속도 제한, Bedrock·Google Cloud 프로젝트 할당량, 게이트웨이 지출 한도, 일시적인 서버 측 제한이 숨어 있을 수 있고, 각각 풀리는 시점과 해결하는 곳이 다릅니다.

`Rate limit reached`라는 포괄적인 문구는 예전 Claude Code가 띄우던 표현입니다. 2026년 10월 5일 기준 [Claude Code 공식 오류 문서](https://code.claude.com/docs/en/errors)에는 이 문구가 없고, 원인별로 구체적인 메시지가 나옵니다. 예전 버전은 플랜에 포함되지 않은 1M 컨텍스트 모델을 고른 경우처럼 권한 문제에도 "Rate limit reached"를 보여 줬고, 이후 [변경 내역](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md)에서 실제 오류와 조치 힌트를 보여 주도록 고쳐졌습니다. 그래서 첫 단계는 Claude Code를 최신 버전으로 올린 뒤 나오는 전체 메시지를 읽고, 아래 표에서 어디가 제한을 걸었는지 찾는 것입니다.

| 지금 보이는 메시지 | 제한을 건 곳 | 먼저 할 일 |
|---|---|---|
| `You've hit your session limit`, weekly·Opus·Sonnet limit `· resets …` | 구독 플랜 사용 한도. Claude.ai·Desktop과 함께 씀 | `/usage`로 재설정 시각 확인. 세션·주간 한도는 모델을 바꿔도 그대로이고, Opus·Sonnet 한도라면 `/model`로 다른 계열 선택 |
| `Usage credits required for 1M context` (옛 버전은 `Rate limit reached`로 표시) | 1M 컨텍스트 사용 권한. 세션·주간 한도가 남아 있어도 발생 | `/model`에서 `[1m]`이 붙지 않은 모델 선택. 메시지가 `/usage-credits`를 안내하면 추가 사용량을 켠 뒤 새 세션 시작 |
| `Request rejected (429)` | API 키의 워크스페이스, Amazon Bedrock 프로젝트, Google Cloud 프로젝트에 설정된 속도 제한 | `/status`로 실제 인증 수단 확인. 남아 있는 `ANTHROPIC_API_KEY`가 구독 대신 쓰일 수 있음. 동시 작업을 줄이고 해당 콘솔에서 한도 확인 |
| `Server is temporarily limiting requests (not your usage limit)` | 플랜과 무관한 일시적 서버 측 제한 | Claude Code가 자동으로 재시도하므로 잠시 대기. 계속되면 status.claude.com 확인 |
| `spend limit reached (daily; resets …)` | 조직이 운영하는 게이트웨이의 지출 한도 | 재시도해도 풀리지 않음. 기간이 바뀌기를 기다리거나 운영자에게 한도 상향 요청 |
| 직접 API 호출의 HTTP 429 `rate_limit_error` | Anthropic 조직·워크스페이스의 요청 수, 입력·출력 토큰 한도 | `retry-after`만큼 기다린 뒤 작은 요청 1회. `enforced_spend_limit_reached`라면 다음 달 1일 00:00 UTC까지 막힘 |
| Claude.ai·Desktop·모바일 화면의 한도 문구 | 플랜 사용 한도 또는 일시적인 용량 부족 | Settings > Usage에서 재설정 시각 확인. 새 채팅은 사용량을 초기화하지 않으므로 긴 대화와 큰 파일부터 줄이기 |

멈춤 규칙은 단순합니다. 어디가 제한을 걸었는지 확인하기 전에는 키, 플랜, 제공업체, 모델을 바꾸지 마세요. 경로를 바꿨더니 오류가 사라졌다면 원인을 찾은 것이 아니라 우회했을 가능성이 큽니다. 모델 변경이 해결책이 되는 경우는 1M 컨텍스트 권한이나 Opus·Sonnet 계열 한도처럼 원인이 메시지로 확인됐을 때뿐입니다.

## 어느 경로에서 제한이 걸렸는지 먼저 찾기

"Rate limit reached"라는 문장만으로는 어떤 한도가 막혔는지 알 수 없습니다. api.anthropic.com을 직접 호출했다면 HTTP 429, 응답 본문, rate-limit 헤더를 봅니다. Claude Code는 `ANTHROPIC_API_KEY`가 설정되어 있으면 구독 세션이 아니라 API 키 워크스페이스의 한도에 걸린 것일 수 있습니다. Bedrock, Vertex AI(Claude Code 문서의 현재 이름은 Google Cloud Agent Platform), 게이트웨이를 거친다면 해당 프로젝트의 할당량, 리전, 테넌트 정책이 제한을 건 곳일 수 있습니다.

먼저 인증 수단, 해당 콘솔의 한도 화면, 같은 모델·제공업체·리전·프롬프트로 한 번 재현되는지를 확인합니다.

Claude Code 터미널에서 이 메시지가 나올 때 로그인 경로, 현재 사용량, 컨텍스트, API 키를 차례로 확인하는 방법은 [Claude Code Rate Limit Reached 해결 가이드](https://blog.laozhang.ai/ko/posts/claude-code-rate-limit-reached)에 있습니다. 실제 오류가 500이나 529였다면 [Claude Code 500과 529: 장애 후 중복 작업 없이 안전하게 재개하기](https://blog.laozhang.ai/ko/posts/claude-code-500-529-rate-limit)를 보세요.

![Claude 사용 경로별로 사용량 화면, 인증 상태, API 응답과 프로젝트 로그를 확인하는 도식](https://blog.laozhang.ai/posts/ko/claude-rate-exceeded-error/img/explainer-1.webp)

## Claude.ai 또는 Desktop: usage window 먼저 확인

Claude.ai, Desktop, mobile 에서 HTTP headers 없이 error 가 보이면 product surface limit 으로 먼저 처리합니다. Usage limits 는 일정 기간 Claude 를 얼마나 사용할 수 있는지이고, length limits 는 하나의 conversation 이 얼마나 길어질 수 있는지입니다. 긴 chat, 큰 files, tools, Research, connectors, 무거운 model 은 window 를 빠르게 소모합니다.

API key 수정부터 시작하지 마세요. Settings > Usage 를 확인하고 reset time 을 읽고, thread 가 크면 더 작은 새 chat 을 시작하고, 필요 없는 files/tools 를 제거하세요. 새 chat 을 시작해도 이미 쓴 사용량은 초기화되지 않습니다. Capacity constraints 는 일시적 load management 일 수 있으며 status page outage 로 보이지 않을 수 있습니다.

## Direct Anthropic API 는 header 를 믿기

Direct Anthropic API 의 HTTP 429 는 rate_limit_error 입니다. retry-after, anthropic-ratelimit headers, RPM, input tokens per minute, output tokens per minute 이 다음 행동을 정합니다. 월간 사용량이 남아도 분 단위로 계속 채워지는 토큰 한도는 막힐 수 있습니다.

예외가 하나 있습니다. 429 본문의 `error.details.error_code`가 `enforced_spend_limit_reached`라면 사용 등급의 월간 지출 상한에 닿은 것입니다. 이때는 `retry-after`가 없고, 다음 달 1일 00:00 UTC가 되거나 한도 상향이 승인될 때까지 풀리지 않습니다. 조직이나 워크스페이스에 직접 정한 지출 한도는 보통 429가 아니라 400 `invalid_request_error`로 돌아옵니다.

다음 요청은 작고 느려야 합니다. concurrency 를 낮추고, 실제로 생성되는 출력을 줄이고, 작업을 나누고, cache 를 쓰고, 같은 경로에서 한 번만 retry 합니다. 직접 API 에서는 `max_tokens` 값만으로 출력 토큰 한도가 미리 차감되지 않습니다.

![직접 API 429의 속도 제한과 사용 등급 월간 지출 상한을 구분하는 흐름](https://blog.laozhang.ai/posts/ko/claude-rate-exceeded-error/img/explainer-2.webp)

## Claude Code는 /status로 인증 경로부터 확인

Claude Code 에서는 /status 와 credential path 가 우선입니다. ANTHROPIC_API_KEY 가 있으면 subscription 이 아니라 API key workspace 의 제한일 수 있습니다. [Claude Code API 키와 구독 결제](https://blog.laozhang.ai/ko/posts/claude-code-api-key-vs-subscription-billing)와 [Claude Code API 설정](https://blog.laozhang.ai/ko/posts/claude-code-api-configuration)을 같이 보세요.

## usage 가 남아도 요청이 막히는 이유

Rate limit 은 하나의 monthly counter 가 아니라 rolling bucket 입니다. 긴 context 는 input token, 긴 answer 는 output token, 많은 작은 요청은 RPM, 급격한 증가량은 acceleration control 을 건드립니다.

## 다음 요청을 안전하게 고치기

한 번에 하나만 바꾸세요. jitter backoff, worker 제한, max output 감소, queue, request_id 와 headers logging 을 적용합니다. 검증은 같은 경로, 인증 수단, model, workload 로 진행합니다.

## Provider 또는 gateway 제한

Bedrock, Vertex AI, gateway 를 통해 Claude 를 쓰면 제한을 건 곳이 Anthropic Console 이 아닐 수 있습니다. provider quota, project/location limit, gateway log 를 먼저 확인하세요.

## 지원 전달 증거 세트

동일 경로 재현이 다시 실패하면 exact message, timestamp, request_id, headers, model, workspace/project/region, 경로 소유자, status result, minimal reproduction 을 보냅니다. key, token, personal data 는 보내지 마세요.

직접 API 라면 request_id 와 headers 가 핵심입니다. Bedrock 또는 Vertex AI 라면 project, region, quota page 가 핵심입니다. gateway 라면 tenant, upstream route, policy hit 이 핵심입니다. 이 구분이 없으면 support 는 다시 다른 소유자에게 확인하라고 돌려보낼 가능성이 큽니다.

## 자주 묻는 질문

### 한도가 남았는데 클로드 코드에 Rate limit reached가 뜨면?

예전 Claude Code는 플랜에 포함되지 않은 1M 컨텍스트 모델을 고른 경우 같은 권한 오류에도 이 문구를 띄웠습니다. 최신 버전으로 올려 전체 메시지를 확인하고, `Usage credits required for 1M context`가 나오면 `/model`에서 `[1m]`이 붙지 않은 모델을 고르세요. `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하면 1M 모델이 목록에서 숨겨집니다.

### Claude rate limit 오류는 항상 direct API 429 인가요?

아닙니다. 경로 소유자를 먼저 증명해야 합니다.

### 운영 로그에는 무엇을 남겨야 하나요?

마지막 성공 요청, 첫 실패 요청, 현재 실패 요청을 한 줄씩 비교하세요. 경로, 인증 수단, model, region, input size, output limit, concurrency, retry-after, status result 를 기록하면 어떤 한도가 막혔는지 빠르게 좁힐 수 있습니다.

### API key 를 바꿔야 하나요?

먼저 바꾸지 마세요. /status 로 실제 인증 경로를 확인한 뒤 판단합니다.

### usage 가 남아 보이는 이유는?

monthly usage 와 rolling RPM/token/burst window 는 다릅니다.

### status 가 정상이라면?

headers, /status, provider dashboard, gateway logs 를 계속 확인합니다.

### support 에 언제 보내나요?

같은 경로에서 재현되고 위의 증거 세트가 준비된 뒤입니다.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-05.

- [Claude Code 공식 오류 문서](https://code.claude.com/docs/en/errors) (code.claude.com)
- [변경 내역](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md) (raw.githubusercontent.com)