Claude Code 429 오류, 사용량 한도인지 장애인지 가르기
`Request rejected (429)` · `You've hit your session limit` 같은 문구로 한도·일시 제한·키 문제를 가르고 조치하는 순서입니다.
API Error: Request rejected (429) 와 You've hit your weekly limit 는 둘 다 「너무 많이 썼다」처럼 보이지만 원인도 조치도 다릅니다. 문구부터 가릅니다.
[1] 화면의 문구를 아래 표에서 찾습니다. 문구는 공식 오류 문서(Error reference)에 실린 그대로입니다.
| 화면 문구 | 원인 | 사용량 한도? |
|---|---|---|
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 · Sonnet limit | 그 모델 계열만의 한도 | 예 |
API Error: Server is temporarily limiting requests (not your usage limit) | 서버의 짧은 제한 | 아니요 |
API Error: Request rejected (429) · … | API 키·클라우드 프로젝트에 걸린 속도 제한, 또는 중간 프록시의 429 | 구독 한도 아님 |
API Error: Usage credits required for 1M context · … | 1M 컨텍스트를 쓸 권한 문제 | 아니요 |
API Error: Repeated 529 Overloaded errors | API 용량 부족 | 아니요(한도에 안 잡힘) |
[2] 먼저 서비스 상태를 봅니다. status.claude.com 에 진행 중인 장애가 있으면 Rate limit reached · 429 · 529 는 내 쪽 설정과 무관할 수 있습니다. 이때는 기다리거나 /model 로 다른 모델을 씁니다(용량은 모델별로 집계됩니다).
[3] 구독으로 로그인했다면 /usage 로 한도와 초기화 시각을 봅니다. 세션·주간 한도는 모든 모델이 공유하므로 모델을 바꿔도 풀리지 않습니다. 선택지는 아래와 같습니다.
- 메시지의 초기화 시각까지 기다립니다. v2.1.234 부터는 대화형 세션을 열어 두면 초기화 뒤 작업을 이어서 하고, 대기 중에는
Continuing automatically at 3:45pm · esc to cancel가 보입니다. /usage-credits로 추가 사용량을 사거나(Pro·Max), 관리자에게 요청합니다(Team·Enterprise)./rate-limit-options로 위 방법을 한 화면에서 봅니다.- Opus·Sonnet 한도는 해당 계열만 막힙니다.
/model로 다른 계열로 바꿉니다. 모델마다 프롬프트 캐시가 따로라 바꾼 첫 요청은 대화 전체를 다시 읽습니다.
[4] Request rejected (429) 면 구독 한도가 아닙니다. 먼저 /status 로 지금 쓰는 인증이 의도한 것인지 봅니다. 환경에 남은 ANTHROPIC_API_KEY 가 구독 대신 낮은 등급의 키로 요청을 보내는 경우가 문서에 나와 있습니다.
$ env | grep -c ANTHROPIC_API_KEY$ unset ANTHROPIC_API_KEY키가 맞다면 제공자 콘솔에서 현재 한도(등급)를 확인합니다. 병렬 작업이 많으면 동시 실행을 줄입니다. CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 를 낮추고, 서브에이전트를 한꺼번에 많이 돌리지 않고, 대량 스크립트 실행은 /model 로 작은 모델을 씁니다.
[5] Usage credits required for 1M context 는 한도가 남아 있어도 나옵니다. 요금제가 1M 컨텍스트를 사용량 크레딧으로만 제공하기 때문입니다.
/model에서[1m]이 붙지 않은 모델을 고릅니다.- 크레딧을 켰다면 Claude Code 를 다시 시작합니다.
- 계속 나오면 설정 어딘가에
[1m]모델 ID 가 박혀 있는 것입니다. 선택기에서 아예 숨기려면CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 씁니다. - 대화가 200K 토큰을 넘어서 나온 경우는 v2.1.172 부터 자동으로 압축해 표준 한도로 이어 가므로 조치가 필요 없습니다.
[6] Fast mode 를 쓰고 있었다면, 그 한도는 일반 Opus 와 따로 있습니다. 한도에 닿으면 Fast mode 가 자동으로 표준 속도로 내려가고(↯ 아이콘이 회색), 쿨다운이 끝나면 다시 켜집니다. 오류가 아니므로 /fast 로 직접 끄지 않아도 됩니다.
[7] 위를 다 거쳤는데 같은 429 가 계속되면 GitHub 이슈에 올리기 전에 이미 있는 글을 찾아봅니다. 문구만 적은 이슈(#48191, Request rejected (429) · Rate limited)는 원인 확인 없이 비활성으로 닫혔습니다. 쓰는 버전 · 인증 방식(구독/API 키/클라우드) · /status 결과 · 발생 시각을 함께 적습니다.
다른 오류 문구는 Claude Code 오류 문구별 조치에서 찾습니다.