문제 해결 · Claude Code
Claude Code API Error 429 (rate_limit_error) 원인과 해결 방법
계정의 요청 속도 또는 동시성 한도에 도달하면 Claude Code는 API Error: 429 rate_limit_error를 출력합니다. GPT와 Gemini 모델에서 병렬 에이전트가 왜 이를 유발하는지, 어떻게 해결하는지 설명합니다.
표시되는 내용
API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limit reached. Please retry shortly."}}발생 원인
- 키가 속한 계정의 요청 속도 또는 동시성 한도를 넘었습니다. Claude Code는 GPT와 Gemini 요청을 Messages API로 보내며, 이 엔드포인트는 한도 초과를 429 rate_limit_error로 알립니다.
- 여러 Claude Code 세션이나 서브에이전트가 같은 키로 병렬 실행되고 있습니다 — 각각이 매 턴마다 요청을 보내므로 버스트가 보기보다 빠르게 쌓입니다.
- google/* 모델에서는 본문 텍스트가 Gemini 쪽에서 옵니다 — Resource has been exhausted. Please retry later. — 상태 코드와 error.type은 같습니다.
- 첫 429를 일으킨 버스트 위에 재시도가 쌓이면 버스트가 줄어들지 않고 오히려 커집니다.
해결 방법
- 잠시 기다리세요 — Claude Code는 자동으로 재시도하고 Retry-After를 지킵니다. 계속 반복되면 한 키를 공유하는 세션 수를 줄이세요.
- 서브에이전트와 병렬 세션을 동시에 더 적게 실행하세요 — 병렬 요청이 가장 먼저 한도에 닿습니다.
- HTTP 402와 혼동하지 마세요 — 그것은 빈 선불 잔액입니다. 429는 재시도 가능한 처리량 문제입니다. 402는 충전하고, 429는 Retry-After를 지키세요.
- 계정이 허용하는 것보다 꾸준히 더 많은 처리량이 필요하다면 스크립트에서 동시성을 제한하고 지원팀에 문의하세요. 402를 429처럼 재시도하지 마세요.
관련 검색어
claude code api error 429claude code rate limit error
자주 묻는 질문
Claude Code의 API Error 429는 선불 잔액이 바닥났다는 뜻인가요?+
아니요. 429는 처리량 문제입니다. 빈 선불 잔액은 HTTP 402입니다. 429는 Retry-After를 지키고, 402는 충전하세요.
Claude Code가 429를 스스로 재시도하나요?+
네 — 자동으로 백오프하고 재시도합니다. 오류가 계속된다면 창이 비워지는 속도보다 버스트가 더 빨리 채워지고 있는 것이며, 보통 같은 키의 병렬 세션 때문입니다.
Claude Code에서 고른 모델에 따라 429가 달라지나요?+
openai/*와 google/* 모델의 상태 코드와 error.type은 같습니다. 텍스트만 다릅니다: GPT 모델은 Rate limit reached. Please retry shortly., Gemini 모델은 Resource has been exhausted. Please retry later.를 반환합니다.