Claude Code 529 Overloaded·사용량 제한 오류: 메시지별 해결

작업이 한창일 때 Claude Code가 API Error: Repeated 529 Overloaded errors를 띄우고 멈추면, 제일 먼저 드는 생각은 “내 한도가 다 됐나?“일 겁니다. 그런데 한도와 관련된 오류 메시지는 생각보다 여러 갈래이고, 갈래마다 할 일이 정반대예요. 어떤 건 기다리면 풀리고, 어떤 건 모델을 바꿔야 하고, 어떤 건 모델을 바꿔도 소용없습니다.

529 Overloaded와 (not your usage limit)은 서버 쪽 사정이라 잠시 뒤 다시 하거나 /model로 모델을 바꾸면 됩니다. You've hit your session limit·weekly limit은 모델을 바꿔도 안 풀리니 리셋 시각까지 기다려야 하고요. Request rejected (429)라면 /status로 어떤 키로 요청이 나가는지부터 보세요.

2026년 9월 16일 Claude Code·Claude API 공식 문서 기준입니다. 아래 오류 문자열은 공식 오류 목록에 실린 형태 그대로이고, 재시도 횟수와 게이트웨이를 거칠 때의 문구는 10월 14일 로컬 가짜 서버로 직접 재 봤습니다.

메시지 문구로 먼저 가르기

화면에 뜬 오류에서 아래 문구를 찾아보세요. 무엇이 막혔는지와 할 일이 거기서 바로 갈립니다.

메시지에 있는 문구	막힌 것	할 일
Repeated 529 Overloaded errors	전체 이용자 API 용량	잠시 뒤 재시도, 급하면 모델 변경
529 Overloaded(Repeated 없음)	ANTHROPIC_BASE_URL로 붙인 서버	그 게이트웨이 상태·로그 확인
(not your usage limit)	서버의 단기 스로틀	잠깐 기다렸다 재시도
Request rejected (429)	API 키·클라우드 프로젝트 한도	자격 증명 확인, 동시 실행 줄이기
hit your session limit·weekly limit	플랜 세션·주간 한도	리셋 시각까지 대기
hit your Opus limit·Sonnet limit	그 모델 계열 한도	다른 계열 모델로 변경
spend limit	크레딧·게이트웨이 지출 상한	상한 올리기 또는 대기

비슷해 보여도 성격이 다른 두 가지를 먼저 갈라 두면 덜 헷갈립니다. “한도”는 내 계정이나 키에 걸린 양이고, “과부하·스로틀”은 서버 사정입니다. 공식 오류 목록의 “사용 한도” 절에 실린 항목 중에도 서버 스로틀, 1M 컨텍스트 사용 크레딧 확인, 응답 없이 닫힌 동의 프롬프트는 할당량 소진과 다르게 동작해요.

화면에 떴다면 이미 10번 다시 보낸 뒤

오류가 보였다는 건 Claude Code가 이미 꽤 버텨 본 뒤라는 뜻입니다. 일시적인 실패는 지수 백오프로 최대 10번 다시 보낸 다음에야 오류로 보여 주거든요.

재시도하는 동안에는 스피너에 Retrying in Ns · attempt x/y가 붙습니다. 그러니 같은 요청을 연타하기보다 메시지 갈래부터 확인하는 게 낫습니다.

10월 14일 테스트 환경(Windows 11 · Windows PowerShell 5.1, Claude Code 2.1.296)에서 몇 번, 얼마나 버티는지 세어 봤습니다. 모든 요청에 529 overloaded_error만 돌려주는 가짜 API 서버를 로컬에 띄우고 ANTHROPIC_BASE_URL을 그쪽으로 돌렸어요.

기본값 그대로 claude -p를 돌리니 첫 요청을 포함해 11번 보낸 뒤, 187초 만에 오류로 끝났습니다. 서버에 찍힌 요청 간격은 0.6초, 1.1초, 2.2초, 4.5초, 8.2초로 두 배씩 늘다가 20초를 거쳐 35~40초 언저리에서 더 늘지 않았어요. CLAUDE_CODE_MAX_RETRIES=3으로 줄이면 4번 보내고 6초 만에 끝났습니다.

응답 도중에 온 실패는 다시 보내지 않을 때도 있습니다. Claude가 텍스트나 도구 호출을 이미 끝낸 뒤 다시 보내면 같은 도구 호출이 두 번 실행될 수 있어서, 끝난 부분을 살려 턴을 이어 가는 거예요.

재시도는 환경 변수로 조절합니다.

환경 변수	기본값	바꾸면
CLAUDE_CODE_MAX_RETRIES	10	재시도 횟수(v2.1.186부터 상한 15)
CLAUDE_CODE_RETRY_WATCHDOG	꺼짐	1이면 429·529를 끝없이 재시도
API_TIMEOUT_MS	600000	요청 하나의 제한 시간(밀리초)

v2.1.199부터는 CLAUDE_CODE_RETRY_WATCHDOG를 켜면 재시도 기본값이 올라가고 15 상한이 없어집니다. CI처럼 지켜보는 사람이 없는 실행에 맞는 설정이에요.

다만 표준 속도 요청이 spend limit이나 사용 크레딧 소진을 알리는 429를 받으면 바로 실패하고, 게이트웨이의 spend limit 429도 스로틀이 아니라서 재시도하지 않습니다.

API_TIMEOUT_MS는 느린 네트워크나 프록시에서 올리면 됩니다.

서브에이전트가 Agent terminated early due to an API error로 멈췄다면, 한도나 서버 오류 재시도 소진으로 서브에이전트의 요청이 최종 실패한 것입니다. 콜론 뒤에 붙은 오류 내용을 맨 위 표에서 다시 찾아 그 항목대로 처리하세요.

529와 not your usage limit, 서버 쪽 사정

두 오류 모두 내 사용량과는 상관없습니다. 기다리면 풀리고, 급하면 모델을 바꾸면 돼요.

API Error: Repeated 529 Overloaded errors

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

전체 이용자의 요청이 몰려 API 용량이 잠시 찬 것입니다. Claude API에서도 529는 overloaded_error이고, 할당량에서 빠지지 않습니다. 529가 떴다고 사용량이 깎이지는 않는다는 얘기예요.

1. status.claude.com에서 용량 공지를 확인합니다.
2. 몇 분 뒤 다시 시도합니다.
3. 급하면 /model로 다른 모델을 고릅니다. 용량은 모델별로 따로 셉니다.

한 모델에 부하가 몰리면 Opus is experiencing high load, please use /model to switch to Sonnet 같은 안내가 먼저 뜨기도 합니다.

기본 주소 대신 ANTHROPIC_BASE_URL로 붙인 위의 가짜 서버 실험에서는 문구가 달랐습니다. Repeated가 빠지고, 상태 페이지 대신 게이트웨이 주소를 보라는 안내가 붙었어요.

API Error: 529 Overloaded. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (<게이트웨이 주소>).

괄호 안에는 붙인 서버의 주소가 찍힙니다. 위 캡처에서는 127.0.0.1:18531이었어요.

이 문구라면 Anthropic 상태 페이지보다 그 게이트웨이의 상태와 로그를 먼저 보면 됩니다.

API Error: Server is temporarily limiting requests (not your usage limit)

API Error: Server is temporarily limiting requests (not your usage limit)

플랜 할당량과 상관없는 짧은 스로틀입니다. Claude Code는 진짜 한도 응답에 붙는 통합 할당량 헤더가 없는 것을 보고 이 경우를 가려냅니다.

잠깐 기다렸다 다시 보내면 되고, v2.1.199부터는 로그인 방식과 상관없이 이 오류도 백오프를 두고 자동 재시도한 뒤에 뜹니다. 계속되면 상태 페이지를 보세요.

Request rejected (429), 어떤 키로 나가나

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

같은 가짜 서버가 429 rate_limit_error를 돌려주게 바꾸니 API Error: Request rejected (429) · Rate limited로 끝났습니다. 가운데 점 뒤에는 서버가 보낸 오류 메시지가 그대로 붙었고, 이것도 오류가 뜨기 전에 재시도를 다 썼어요.

API 키, Amazon Bedrock 프로젝트, Google Cloud 프로젝트에 설정된 속도 한도에 걸린 것입니다. 구독으로 쓰는 줄 알았는데 이 오류가 났다면, 요청이 다른 자격 증명으로 나가고 있을 가능성이 큽니다. 저라면 아래 순서로 봅니다.

1. /status로 지금 쓰는 자격 증명 확인

셸에 남아 있는 ANTHROPIC_API_KEY 때문에 구독 대신 등급이 낮은 키로 요청이 나갈 수 있습니다. 의도한 자격 증명이 아니면 그 변수를 지우고 다시 시작하세요.

2. 그 키나 프로젝트의 콘솔에서 현재 한도 보기

Claude 콘솔, Bedrock, Google Cloud 중 요청이 실제로 나가는 곳의 한도를 확인합니다.

3. 동시 요청 줄이기

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY를 낮추고, 병렬 서브에이전트를 많이 띄우지 않고, 대량 스크립트 실행에는 더 작은 모델을 씁니다. 작업을 여러 갈래로 나누는 구성이라면 서브에이전트를 어떤 일에 나눠 쓰는지를 먼저 정리해 두면 동시 요청이 줄어듭니다.

사용량이 갑자기 늘어서 429가 늘어난 걸 수도 있을까요? 드물게 그렇습니다.

조직의 사용량이 갑자기 늘면 API의 가속 한도 때문에 429가 날 수 있어요. 이때는 트래픽을 조금씩 올리고 사용 패턴을 일정하게 유지하는 것이 권장 대응입니다.

hit your … limit, 기다릴지 모델을 바꿀지

You’ve hit your session limit · resets 3:45pm

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 · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

구독 플랜의 사용 할당량이 찬 것입니다. 한 번 쓴 양이 세션 창과 주간 창에 동시에 쌓이므로, 큰 작업 한 번이 세션 창이 리셋되기 전에 주간 할당량까지 다 쓸 수 있습니다.

여기서 모델을 바꾸면 되지 않나 싶은데, 세션·주간 한도는 모든 모델이 함께 쓰는 통이라 바꿔도 풀리지 않습니다. 모델 변경이 통하는 건 Opus limit·Sonnet limit처럼 계열 이름이 붙은 한도뿐이에요.

• 세션·주간 한도라면 메시지의 리셋 시각까지 기다립니다.
• Opus·Sonnet 한도라면 /model로 그 계열 밖 모델을 고릅니다. 모델마다 캐시가 따로라서 바꾼 직후 첫 요청은 대화 전체를 캐시 없이 다시 읽는다는 점은 알아 두세요.
• 더 써야 한다면 /usage-credits에서 Pro·Max는 추가 사용량을 사고, Team·Enterprise는 관리자에게 요청합니다.

claude.ai 구독으로 로그인한 대화형 세션은 세션을 열어 둔 채 기다렸다가 리셋 직후 작업을 이어 가기도 합니다. 그동안 아래쪽에 Usage limit reached · continuing automatically at 3:45pm · esc to cancel이 보여요. 남은 양을 읽는 법은 사용량 확인법과 5시간·주간 한도에 정리했습니다.

spend limit은 지출 상한

You’ve hit your monthly spend limit

You've hit your monthly spend limit · raise it at claude.ai/settings/usage
You've hit your individual spend limit · ask your admin for a higher limit

이름은 비슷하지만 사용 한도가 아니라 지출 상한입니다. 플랜 사용량으로 이 요청을 감당할 수 없고, 대신 쓸 사용 크레딧이 지출 상한에 닿은 거예요.

플랜의 사용 창 하나가 찼을 때, 또는 크레딧으로만 청구되는 모델처럼 크레딧으로만 지불되는 요청일 때 납니다. 메시지가 가리키는 곳에서 상한을 올리거나, 리셋 시각이 적혀 있으면 그때까지 기다리세요.

게이트웨이를 거쳐 접속하다 소문자 spend limit reached를 봤다면 플랜이 아니라 게이트웨이 운영자가 건 상한입니다. 기다리거나 운영자에게 상향을 요청하세요.

spend limit reached (daily; resets 2026-08-09 00:00 UTC)

이 응답은 x-should-retry: false가 붙어 재시도 없이 바로 뜹니다.

다른 사람들이 겪은 문제

GitHub 이슈를 찾아보면 병렬로 많이 돌릴 때 오류가 반복된다는 보고와, 잔여량이 남았는데 거절당했다는 보고가 눈에 띕니다. 원인을 확정한 보고는 없습니다.

병렬 실행에서 난 경우부터 보면 이렇습니다.

• awaliuddin(2026-06-15, #68502): Claude Code 2.1.176에서 세션을 5~10개 넘게 병렬로 돌리고 일부가 서브에이전트까지 띄울 때 529와 스로틀 메시지가 반복됐다고 보고했습니다. “not planned”로 닫혔습니다.
• JayDeeAU(2026-04-07, #44481): Max 플랜에서 팀원 5명을 동시에 돌리자 5~10분 안에 429·529가 나기 시작했다고 보고했습니다. 완화책으로 팀원 작업에 시차 두기, 조사 작업을 순서대로 돌리기, 무거운 단계에서 팀 규모 줄이기를 들었습니다.

잔여량과 거절이 어긋나 보인 경우도 있습니다.

• afnanmakhdoom7(2026-04-20, #51291): (not your usage limit) 메시지가 뜨는 동안 쓰지 않은 플랜 사용량이 크게 줄었다고(세션 약 26%) 보고했습니다. 보고자는 스로틀이 사용량처럼 계산되는 버그를 추정했습니다.
• C0dino(2026-02-03, #22876): 대시보드가 세션 72%·주간 6%·Claude Code 0%인데도 429가 왔다고 보고했습니다. OpenClaw 게이트웨이를 거친 OAuth 연결이라 직접 접속과 상황이 다릅니다.

병렬 실행이 있다면 동시 요청 수부터 줄여 보세요. 잔여량과 거절이 어긋나 보이면 게이트웨이나 환경 변수처럼 요청이 지나가는 경로를 먼저 보는 게 좋습니다.

마치며

한도 오류는 메시지가 길고 비슷비슷해서 다 같은 “한도 초과”로 읽히기 쉽습니다. 하지만 서버 사정인지, 내 계정의 양인지, 지출 상한인지에 따라 할 일이 완전히 달라요. 529와 not your usage limit은 할당량에서 빠지지 않으니 기다리거나 모델을 바꾸면 되고, 세션·주간 한도는 모델을 바꿔도 안 풀리며, 429는 요청이 나가는 자격 증명부터 봐야 합니다.

그래서 저는 오류가 뜨면 재시도 버튼보다 메시지에서 맨 위 표의 문구부터 찾아보길 권합니다. 한도에 자주 닿는다면 컨텍스트가 찰 때 무엇이 일어나고 무엇으로 관리하는지를 맞춰 두는 것이 요청 하나의 크기를 줄이는 가장 빠른 길입니다.