문제 해결 · 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 하거나, 긴 히스토리를 끌고 다니지 말고 새 세션을 시작하세요.
- "Claude usage limit reached"와 혼동하지 마세요 — 그것은 리셋 시각이 있는 구독 한도이지 분당 처리량이 아닙니다. 해결 방법이 다릅니다.
- 키의 조직이 허용하는 것보다 지속적으로 더 많은 처리량이 필요하다면, 그것은 재시도 문제가 아니라 용량 협의 사안입니다 — 프로바이더와 상의하세요.
관련 검색어
claude code api error 429claude code rate limit error
자주 묻는 질문
Claude Code의 API Error 429는 구독이 소진됐다는 뜻인가요?+
아니요. 429는 API 키의 분당 처리량입니다. 구독 소진은 리셋 시각과 함께 "Claude usage limit reached"로 표시됩니다.
Claude Code는 429를 스스로 재시도하나요?+
네 — 자동으로 백오프하며 재시도합니다. 오류가 지속된다면 윈도우가 비워지는 속도보다 버스트가 다시 채워지는 속도가 빠른 것으로, 보통 같은 키를 쓰는 병렬 세션이 원인입니다.
거대한 프롬프트 하나가 왜 단독으로 429를 일으키나요?+
레이트 리밋은 분당 토큰 수로 계산되며, 지나치게 큰 컨텍스트 하나가 요청 한 번에 그 분의 예산 전체를 써버릴 수 있습니다.