문제 해결 · Claude Code
Claude Code API Error 429 (rate_limit_error) 원인과 해결 방법
Claude Code는 분당 처리량이 소진되면 API Error: 429 rate_limit_error를 출력합니다. 이 한도가 실제로 무엇인지, 병렬 에이전트가 왜 이를 유발하는지, 어떻게 해결하는지 설명합니다.
표시되는 내용
API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"This request would exceed your organization's rate limit of 80,000 input tokens per minute. Please reduce the prompt length or the maximum tokens requested, or try again later."}}발생 원인
- 키 뒤에 있는 API 조직의 분당 토큰 또는 요청 한도를 초과했습니다. 메시지의 숫자는 해당 조직 고유의 한도이므로 계정마다 다릅니다.
- 같은 키로 여러 Claude Code 세션이나 서브에이전트가 병렬로 실행 중입니다 — 각 세션이 매 턴마다 전체 컨텍스트를 다시 전송하므로 버스트가 보기보다 빠르게 쌓입니다.
- 매우 큰 컨텍스트 하나만으로도 분당 토큰 예산을 초과할 수 있으며, 그래서 메시지가 대기뿐 아니라 프롬프트 단축도 제안하는 것입니다.
- 첫 429를 유발한 버스트 위에 재시도가 겹겹이 쌓여, 상황을 해소하는 대신 키우고 있습니다.
해결 방법
- 1분 윈도우가 지나가길 기다리세요 — Claude Code는 자동으로 재시도하며 Retry-After를 준수합니다. 계속 반복되면 하나의 키를 공유하는 세션 수를 줄이세요.
- 각 턴이 실어 나르는 양을 줄이세요: 비대해진 대화는 /compact 하거나, 긴 히스토리를 끌고 다니지 말고 새 세션을 시작하세요.
- HTTP 402 billing_error와 혼동하지 마세요 — 그건 선불 잔액이 비었다는 뜻입니다. 429는 재시도 가능한 처리량입니다. 402는 충전하고, 429는 Retry-After를 지키세요.
- 키가 허용하는 것보다 지속적으로 더 많은 처리량이 필요하면 동시성을 제한하거나 키를 나누세요. 402를 429처럼 재시도하지 마세요.
관련 검색어
claude code api error 429claude code rate limit error
자주 묻는 질문
Claude Code의 API Error 429는 선불 잔액이 비었다는 뜻인가요?+
아니요. 429는 분당 처리량입니다. 빈 선불 잔액은 HTTP 402 billing_error입니다. 429는 Retry-After를 지키고, 402는 충전하세요.
Claude Code는 429를 스스로 재시도하나요?+
네 — 자동으로 백오프하며 재시도합니다. 오류가 지속된다면 윈도우가 비워지는 속도보다 버스트가 다시 채워지는 속도가 빠른 것으로, 보통 같은 키를 쓰는 병렬 세션이 원인입니다.
거대한 프롬프트 하나가 왜 단독으로 429를 일으키나요?+
레이트 리밋은 분당 토큰 수로 계산되며, 지나치게 큰 컨텍스트 하나가 요청 한 번에 그 분의 예산 전체를 써버릴 수 있습니다.