Claude 가 "Rate Exceeded", "Claude Error: Rate limit reached", 또는 Claude Code 429 를 보여주면 하나의 API quota 로 단정하지 마세요. 먼저 발생 surface 를 나눕니다. Claude.ai / Desktop usage window, Claude Code subscription auth, Claude Code API key route, direct Anthropic API, Bedrock / Vertex AI, gateway, 또는 temporary capacity / burst control 일 수 있습니다. 각 surface 의 reset signal 과 owner 는 다릅니다.
| Surface | Owner | First move | Proof | Next step |
|---|---|---|---|---|
| Claude.ai / Desktop / mobile | Claude plan usage window or capacity | Settings > Usage 확인, 긴 chat/files 축소 | 5-hour/session/weekly reset, usage bars, capacity text | 더 작은 새 chat, 대기, extra usage, later retry |
| Claude Code subscription auth | Claude surface 와 공유되는 plan/session window | /usage 또는 reset message 확인 | session limit, weekly limit, model limit | reset 대기, model/workload 낮추기 |
| Claude Code API key | Console workspace or cloud project | /status 로 active credential 확인 | API-key route, provider logs, 429 body | concurrency 감소 또는 owner dashboard 확인 |
| Direct Anthropic API | Anthropic workspace/model rate limit | retry-after 대기 후 request 축소 | HTTP 429, rate_limit_error, rate-limit headers | 같은 route 에서 작은 request 1회 retry |
| Bedrock / Vertex AI / gateway | provider project, region, tenant, proxy policy | provider/gateway logs 확인 | Provider 429, throttling, tenant policy | 해당 quota 조정 또는 operator 문의 |
| Capacity / burst / acceleration | service load or traffic shape | 잠시 대기, status 확인, ramp 완화 | capacity text, recent incident, RPS spike | later retry 또는 작은 동일 route 요청 검증 |
중지 규칙은 단순합니다. owner 확인 전에는 key, plan, provider, model 을 바꾸지 마세요. route 를 바꿔 error 가 사라졌다면 진단이 아니라 우회일 수 있습니다.
제한을 만든 route 를 먼저 찾기
rate limit reached 라는 문장만으로는 어떤 bucket 이 막혔는지 알 수 없습니다. api.anthropic.com 직접 호출이면 HTTP 429, response body, rate-limit headers 를 봅니다. Claude Code 는 ANTHROPIC_API_KEY 가 설정되어 있으면 API-key workspace 문제일 수 있고 subscription session 과 다릅니다. Bedrock, Vertex AI, gateway 는 provider quota, region, tenant policy 가 owner 일 수 있습니다.
먼저 credential, owner dashboard, 같은 model/provider/region/prompt 로 한 번 재현 가능한지 확인합니다.
Claude Code 500, 529, plan window 는 Claude Code 500/529/rate limit router를 사용하세요. Claude Code rate limit 세부는 Claude Code rate limit에 있습니다.
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 를 제거하세요. 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 이 다음 행동을 정합니다. 월간 사용량이 남아도 rolling minute bucket 은 막힐 수 있습니다.
다음 요청은 작고 느려야 합니다. concurrency 를 낮추고, max output 을 줄이고, 작업을 나누고, cache 를 쓰고, 같은 route 에서 한 번만 retry 합니다.
Claude Code 는 active route 부터 확인
Claude Code 에서는 /status 와 credential path 가 우선입니다. ANTHROPIC_API_KEY 가 있으면 subscription 이 아니라 API key workspace 의 제한일 수 있습니다. API key vs subscription billing 과 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 을 적용합니다. 검증은 같은 route, credential, model, workload 로 진행합니다.
Provider 또는 gateway 제한
Bedrock, Vertex AI, gateway 를 통해 Claude 를 쓰면 Anthropic Console 이 owner 가 아닐 수 있습니다. 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 는 다시 다른 소유자에게 확인하라고 돌려보낼 가능성이 큽니다.
자주 묻는 질문
항상 direct API 429 인가요?
아닙니다. 경로 소유자를 먼저 증명해야 합니다.
운영 로그에는 무엇을 남겨야 하나요?
마지막 성공 요청, 첫 실패 요청, 현재 실패 요청을 한 줄씩 비교하세요. route, credential, model, region, input size, output limit, concurrency, retry-after, status result 를 기록하면 어떤 bucket 이 막혔는지 빠르게 좁힐 수 있습니다.
API key 를 바꿔야 하나요?
먼저 바꾸지 마세요. active route 를 확인한 뒤 판단합니다.
usage 가 남아 보이는 이유는?
monthly usage 와 rolling RPM/token/burst window 는 다릅니다.
status 가 정상이라면?
headers, /status, provider dashboard, gateway logs 를 계속 확인합니다.
support 에 언제 보내나요?
같은 route 재현과 evidence packet 이 준비된 뒤입니다.