Claude Code 또는 Claude API 호출에서 API Error: Rate limit reached가 나오면, 먼저 retry를 늘리거나 key를 바꾸지 말고 현재 경로를 확인한다. 같은 문구라도 원인은 Claude Code 사용량, API key, provider, credits, 모델/컨텍스트, 또는 Claude Status일 수 있고 각 분기의 해결 방법은 다르다.
| 오류가 나타난 위치 | 먼저 확인할 것 | 가능한 담당 분기 | 다음 행동 |
|---|---|---|---|
| Claude Code 터미널 또는 editor | /status, 로그인 계정, plan, ANTHROPIC_API_KEY | Claude Code 사용량, subscription login, API-key override, context | 같은 세션을 유지하고 경로를 확인한 뒤 대기, 재로그인, 또는 명확한 API 경로로 이동 |
| SDK, curl, server log의 HTTP 429 | API key, organization, project, model, headers, Console Limits | API request/token limit, project/model scope | 요청 또는 token 압력이 증명될 때만 backoff |
| gateway, cloud, provider, hosted app | provider dashboard, upstream body, provider request id | provider quota, wrapper throttle, wrong project, upstream limit | direct Anthropic 조치 전에 provider 쪽을 확인 |
| Console에 credits/billing/spend cap 표시 | credits, billing, usage, spend cap | 계정 자금 또는 billing 상태 | 재시도를 멈추고 account state를 먼저 수정 |
| 특정 model 또는 긴 context에서만 실패 | model, context length, token volume, concurrency | model family 또는 context pressure | context 단축, output 제한, concurrency 하향, 작은 model test |
| 여러 경로가 동시에 실패 | Claude Status, timestamp, request id, recent changes | platform incident 또는 degraded service | 증거를 보관하고 계정 변경을 서두르지 않음 |
재시도 기준은 명확하다. request 수 또는 token 사용량이 실제로 압박을 받고 있고 reset, header, Console, Rate Limits API, provider signal이 있을 때만 retry가 수리 방법이다. credits, billing, wrong project, wrong key, Claude Code allowance, provider quota, status incident라면 같은 요청 반복은 수리가 아니다.
10분 복구 순서
첫 단계는 정확한 오류를 저장하는 것이다. HTTP status, error type, error code, request id, endpoint, model, timestamp, timezone을 남긴다. Claude Code라면 terminal text와 /status를, API라면 response body와 headers를, provider라면 provider request id와 upstream body를 따로 보관한다.
다음은 활성 surface 확인이다. Claude Code, direct Anthropic API, provider, Bedrock, Vertex, gateway는 같은 문구를 보여도 담당자가 다르다. model, key, provider, retry를 동시에 바꾸면 성공해도 원인을 모른다.
세 번째는 scope 확인이다. 같은 project에서 새 key를 만들어도 project-level limit은 고쳐지지 않는다. 작은 model은 billing issue를 고치지 않는다. retry loop는 Claude Code usage window를 고치지 않는다. Console에서 보는 project와 실제 실행 환경의 project가 같은지도 확인한다.
마지막은 same-path 작은 test 하나다. Claude Code는 같은 session에서 짧은 command, API는 같은 key와 model로 작은 request, provider는 같은 provider route에서 최소 요청과 log view를 본다. 목표는 우연히 성공할 때까지 시도하는 것이 아니라 분기를 증명하는 것이다.
API 제한 증거 읽기
Anthropic API limits는 request rate, input tokens, output tokens로 나뉜다. Messages API에서는 RPM, ITPM, OTPM이 중요하다. 요청 수가 적어도 긴 context 또는 큰 output 때문에 token limit에 걸릴 수 있다.
API key 경로가 확인되면 현재 evidence가 오래된 표보다 우선이다. response headers, retry-after, Console Limits, Usage, Billing, Rate Limits API를 본다. 고정 RPM 숫자를 runbook에 쓰려면 현재 account, project, model, tier에서 나온 값인지 명확해야 한다.
| evidence | 의미 | 첫 번째 수리 |
|---|---|---|
| headers 또는 Console이 request pressure를 보여줌 | active window의 요청이 많음 | jitter 포함 backoff, concurrency 하향, tenant별 queue |
| input/output token pressure가 큼 | context 또는 generation이 큼 | context 단축, output cap, task split, 적절한 caching |
| 특정 model만 실패 | model family 또는 선택 model limit | 작은 model test, load 감소, reset 대기 |
backoff는 evidence에 묶여야 한다. client가 retry-after를 제공하면 그것을 따른다. 없다면 exponential backoff with jitter와 최대 시도 횟수를 설정한다. 무제한 retry는 failed traffic을 늘리고 실제 담당 분기를 숨긴다.
Claude Code와 API 제한을 분리하기
Claude Code는 direct API처럼 보이지만 실제로는 subscription login, API key override, team env, provider credential 중 하나로 동작할 수 있다. 먼저 /status를 실행해 현재 session의 경로를 확인한다.
subscription login이면 usage, selected model, context size, parallel sessions를 본다. 긴 coding session은 file summaries, tool outputs, 이전 context를 쌓는다. /compact, 새 session, 작은 model, parallel 감소는 유효한 test가 될 수 있지만 모든 429의 원인으로 처리하면 안 된다.
API key 경로이면 ANTHROPIC_API_KEY, shell profile, project env, CI variables, provider credentials를 확인한다. local terminal과 remote container가 다른 key를 쓰는 경우가 많다. 개발자가 보는 Console project와 실행 중인 project가 다르면 잔액과 limit이 모순처럼 보인다.
unsupported token extraction, OAuth workaround, random proxy는 사용하지 않는다. 경로 증명을 어렵게 만들고 secrets 위험을 만든다. 안전한 선택지는 대기, load reduction, 올바른 login, 또는 monitoring 가능한 API route로 명시적 전환이다.
credits, billing, key ownership
credits나 billing issue도 request가 막히므로 rate limit처럼 보인다. 그러나 retry는 자금이나 spend cap을 수정하지 못한다. Console이 credits, billing, account state 문제를 보여주면 요청을 멈추고 계정 상태를 먼저 수정한다.
key는 organization과 project에 속한다. provider route는 자체 quota, billing, throttle을 가질 수 있다. ticket에는 key 자체가 아니라 organization, project, provider, environment source, deployment environment 같은 안전한 식별자만 남긴다.
Claude subscription과 API usage는 별도 계약이다. Pro/Max는 supported Claude product usage와 Claude Code login path에 영향을 줄 수 있지만 자동으로 API credit wallet이 되지 않는다. credits 구매 전 active branch가 API funding 또는 billing인지 증명해야 한다.
provider, cloud, status 확인
Bedrock, Vertex AI, gateway, hosted app, internal proxy는 각자 quota, project selection, throttle, model mapping, error wrapping을 가진다. upstream Anthropic error body는 유용하지만 direct Anthropic Console이 exhausted라는 증거는 아니다.
provider route에서는 세 가지를 묻는다. provider dashboard에 quota/billing block이 있는가. provider log에 upstream Anthropic request id가 있는가. 같은 작은 request가 direct Anthropic credentials에서도 실패하는가. 이 답으로 provider-owned issue, direct API issue, application throttling을 분리한다.
Claude Status는 별도 분기다. deploy 없이 오류가 급증하거나 여러 environment와 사용자가 동시에 실패하면 status를 본다. degraded status는 기다리는 것이 맞다는 증거가 될 수 있다. green status는 개별 key, project, model, provider, Claude Code session이 정상이라는 뜻은 아니다.
escalation과 예방
support packet은 짧고 완전해야 한다. timestamp와 timezone, exact error body, HTTP status, request id, active path, model, endpoint, 안전한 org/project identifiers, headers, Console/provider limit state, Claude Status state, recent changes를 포함한다. API key, bearer token, session token, private prompt는 포함하지 않는다.
production에서는 tenant별 queue, model family별 concurrency cap, route/project/model/request id/token counts logging을 둔다. Claude Code 팀은 session이 subscription-authenticated인지 API-key-authenticated인지 기록한다. provider는 provider id와 upstream id를 같이 보관한다.
좋은 결과는 limit이 절대 발생하지 않는 것이 아니다. 어떤 경로가 실패했는지, 어떤 evidence가 그것을 증명하는지, retry가 안전한지, 누가 상태를 바꿔야 다음 요청이 성공하는지를 빠르게 아는 것이다.
팀용 재발 방지 체크
팀은 incident template에 active path, credential source, model/context, live limit evidence, retry decision, support packet을 고정해 두는 것이 좋다. 이 중 하나라도 비어 있으면 “rate limit”이라는 결론은 아직 이르다.
CI와 remote container는 local terminal과 다른 environment source를 사용할 수 있다. local /status가 정상이어도 production job이 다른 project key 또는 provider route를 쓰면 같은 조치가 통하지 않는다. startup log에 secrets 없는 safe route summary를 남기면 반복 사고를 줄일 수 있다.
자주 묻는 질문
바로 재시도해도 되나요?
request 또는 token pressure가 증명되고 reset, header, Console, provider signal이 있을 때만 가능하다. credits, billing, wrong project, wrong key, Claude Code allowance, provider quota, status incident라면 재시도를 멈춘다.
Pro/Max인데 Claude Code가 제한을 표시하는 이유는?
Claude Code는 subscription login 또는 API key route로 동작할 수 있다. /status와 ANTHROPIC_API_KEY를 확인한다. subscription은 direct API credits를 의미하지 않는다.
API credits를 사면 해결되나요?
active branch가 API funding 또는 billing이면 도움이 된다. Claude Code usage window, wrong login, provider quota, long context, platform incident에는 도움이 되지 않는다.
1M context가 원인인가요?
원인이 될 수 있지만 하나의 분기다. model, context length, token volume, concurrency, 작은 model test로 확인한다.
provider 경로에서만 실패하면?
provider dashboard와 logs를 먼저 본다. provider는 별도 quota, project, billing, throttle, model mapping을 가질 수 있다. upstream request id가 있으면 provider id와 함께 저장한다.
support에는 무엇을 보내야 하나요?
timestamp, timezone, exact error body, HTTP status, request id, active path, model, endpoint, 안전한 org/project identifiers, headers, Console/provider state, status state, recent changes를 보낸다. secrets는 보내지 않는다.
