Claude Code 529 과부하 오류: 기다릴지, 모델을 바꿀지

Claude Code 작업 중 아래 메시지가 떴다면, Claude Code는 이미 지수 백오프로 최대 10회까지 자동 재시도를 마친 상태입니다. 529는 모든 사용자가 함께 쓰는 API 용량이 일시적으로 가득 찼다는 뜻이며, 공식 문서 기준으로 내 사용량 한도가 아니고 할당량에서 차감되지도 않습니다.

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.

용량은 모델별로 관리됩니다. 그래서 작업을 바로 이어가야 한다면 /model로 다른 모델로 바꾸는 것이 가장 빠르고, 데스크톱 앱의 Code 탭에서는 모델 선택기로 바꿉니다. 급하지 않다면 몇 분 뒤 다시 보내면 됩니다. 과부하로 자주 멈춘다면 fallback 모델 체인을 설정해 두고, CI처럼 사람이 지켜보지 않는 실행이라면 CLAUDE_CODE_RETRY_WATCHDOG=1로 실패 대신 기다리게 할 수 있습니다. 아래에 정리한 동작은 2026년 9월 28일 기준 Claude Code 오류 문서와 모델 설정 문서에 적힌 내용입니다.

메시지가 뜨기 전에 이미 끝난 재시도

Claude의 응답이 흘러나오기 전에 서버 오류, 과부하 응답, 타임아웃이 발생하면 Claude Code는 요청을 자동으로 다시 보냅니다. 재시도하는 동안 스피너에는 Retrying in Ns · attempt x/y 카운트다운이 보입니다. 처음에는 오류 이름이 API error로만 표시되다가, v2.1.198부터는 세 번째 시도부터 구체적인 원인으로 바뀌고, 원인이 529 과부하라면 카운트다운 아래 줄에 상태를 확인할 곳도 함께 나옵니다.

이 동작을 알면 두 가지 판단이 쉬워집니다.

• 메시지를 보자마자 같은 요청을 연달아 보내는 것은 Claude Code가 방금 끝낸 재시도를 한 번 더 하는 것과 비슷합니다. 원래 메시지는 대화에 그대로 남아 있으므로, 몇 분 기다렸다가 try again처럼 짧게 보내도 이어집니다.
• 요금제를 올리거나 Claude Code를 다시 설치할 이유가 없습니다. Claude API 오류 문서는 529를 전체 사용자 트래픽이 몰릴 때 생기는 overloaded_error로 정의합니다. 내 키나 조직의 한도를 넘었을 때는 529가 아니라 429가 옵니다.

지금 무엇을 할지 고르는 기준

어느 모델이 여유 있는지는 시점마다 달라서 고정된 정답이 없습니다. 판단 근거로 쓸 수 있는 것은 Claude Code가 메시지에서 직접 제안하는 모델, 그리고 상태 페이지 장애 제목에 이름이 오르지 않은 모델 두 가지입니다. 데스크톱 앱(Code 탭, Cowork)에서는 같은 상황의 메시지가 Opus is experiencing high load. Switch to Sonnet.으로 표시됩니다.

내 경로의 상태 페이지 찾기

메시지 마지막 문장은 사용 경로에 따라 달라지고, 바로 그 문장이 어느 상태 페이지를 봐야 하는지 알려 줍니다.

게이트웨이를 거쳐 쓰고 있다면 메시지에 게이트웨이 호스트가 찍히므로, 먼저 그 게이트웨이 운영 측의 상태 페이지나 지원 창구를 확인하는 것이 순서입니다.

status.claude.com을 볼 때는 요약 색보다 장애 목록의 제목을 읽는 것이 쓸모 있습니다. 2026년 9월 28일 기준 이 페이지의 구성 요소는 claude.ai, Claude Console, Claude API, Claude Code, Claude Cowork, Claude for Government이고 모델별 항목은 따로 없습니다. 반면 장애 제목에는 모델 이름이 자주 들어갑니다. 9월 15일 "Intermittent error spikes for Claude Mythos 5.1 and Claude Fable 5.1", 9월 2~3일 "Elevated errors for Claude Sonnet 5", 9월 22일 "Elevated errors for multiple models"가 그런 예입니다. 요약이 "All Systems Operational"이어도 특정 모델의 용량 상태까지 보여 주는 것은 아니므로, 내 모델 이름이 들어간 최근 공지가 있는지 확인하세요. 제목에 내 모델만 있다면 모델 전환이 통할 가능성이 높은 상황입니다.

자신이 어느 경로로 요청을 보내는지 헷갈린다면 /status에서 활성 자격 증명을 확인합니다. 셸에 ANTHROPIC_API_KEY가 설정되어 있으면 로그인한 상태여도 구독 대신 그 키가 쓰입니다. 대화형 모드에서는 처음 한 번 승인을 묻지만, -p 비대화형 실행에서는 항상 키가 쓰입니다. 구독으로 돌아가려면 unset ANTHROPIC_API_KEY를 실행합니다.

다음 과부하에 멈추지 않도록 fallback 체인 설정

fallback 체인을 설정해 두면, 주 모델이 과부하이거나 사용할 수 없거나 재시도할 수 없는 서버 오류를 돌려줄 때 Claude Code가 요청을 실패시키지 않고 다음 모델로 넘어갑니다. 전환될 때는 알림이 표시됩니다.

이번 세션에만 적용하려면 실행 플래그를 씁니다.

claude --fallback-model sonnet,haiku

계속 적용하려면 설정 파일(모든 프로젝트에 적용하려면 ~/.claude/settings.json)에 배열로 넣습니다. 아래 모델 ID는 2026년 9월 28일 기준 공식 문서의 예시입니다.

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

설정하기 전에 알아 둘 제약은 다음과 같습니다.

• 전환은 현재 턴에만 적용됩니다. 다음 메시지는 다시 주 모델부터 시도합니다.
• 중복을 제거한 뒤 최대 3개 모델까지만 쓰고, 나머지 항목은 무시합니다.
• 플래그가 설정 파일보다 우선합니다. 항목에는 모델 이름이나 별칭을 쓸 수 있고, "default"는 기본 모델을 뜻합니다.
• 인증, 결제, 요청 한도(429), 요청 크기, 전송 계층 오류와 조직 정책에 따른 거부에는 전환하지 않습니다. 화면의 오류가 429라면 fallback 체인은 도움이 되지 않습니다.
• 시작할 때 체인을 확인해 주지 않고 /status에도 표시되지 않습니다. 실제로 전환될 때 뜨는 알림이 설정이 살아 있다는 첫 신호입니다.
• availableModels로 허용되지 않은 모델은 체인에서 빠집니다. 컨텍스트 압축 중에는 주 모델보다 컨텍스트 창이 작은 모델로 넘어가지 않습니다.
• v2.1.247부터는 서브에이전트 요청에도 체인이 적용됩니다.

체인을 짤 때는 서로 다른 계열의 모델을 섞어 두는 편이 낫습니다. 같은 장애 제목에 함께 오른 모델끼리만 묶으면 둘 다 막힐 수 있기 때문입니다.

CI와 스크립트에서 실패하지 않고 기다리게 하기

사람이 지켜보지 않는 실행에서는 529 한 번에 작업 전체가 실패하는 것이 가장 큰 손실입니다. 이럴 때 쓰는 것이 CLAUDE_CODE_RETRY_WATCHDOG입니다.

# 과부하(529)와 일시적 요청 제한(429)을 포기하지 않고 계속 재시도
export CLAUDE_CODE_RETRY_WATCHDOG=1
claude -p "실패한 테스트의 원인을 정리해 줘"

이 값을 1로 두면 Claude Code는 429와 529 용량 오류를 CLAUDE_CODE_MAX_RETRIES 횟수에서 멈추지 않고 무기한 재시도하며, 시도 사이 간격은 최대 5분까지 늘어납니다. v2.1.199부터는 서버 오류, 타임아웃, 연결 끊김 같은 다른 일시적 오류의 기본 재시도 횟수도 300회(약 3시간 분량의 백오프)로 늘어납니다. 다만 v2.1.239부터는 지출 한도나 사용량 크레딧 소진을 알리는 429를 받으면 기다리지 않고 바로 실패합니다. 이 변수는 v2.1.186 이상에서 동작합니다.

무기한 대기는 러너 시간을 계속 쓰므로, CI 쪽에 작업 제한 시간을 따로 걸어 두는 것이 안전합니다. 또 -p 실행에서는 ANTHROPIC_API_KEY가 항상 쓰이므로, 파이프라인의 한도와 청구도 그 키를 기준으로 계산됩니다.

반대로 스크립트가 빨리 실패하고 다른 조치로 넘어가야 한다면 재시도 횟수를 줄입니다. 기본값은 10이고, v2.1.186부터 상한은 15입니다.

export CLAUDE_CODE_MAX_RETRIES=3

과부하처럼 보이지만 다른 오류일 때

화면에 "막혔다"는 느낌은 같아도 문구가 다르면 가야 할 곳이 다릅니다.

응답 중간에 끊긴 경우는 따로 주의가 필요합니다. v2.1.199부터 Claude Code는 Claude가 이미 완성한 텍스트와 도구 호출을 남겨 두고, 끝난 도구 호출은 실행한 뒤 그 결과에서 턴을 이어갑니다. 요청을 통째로 다시 보내지 않는 이유는 같은 도구 호출이 두 번 실행될 수 있기 때문입니다. 따라서 이 문구를 봤다면 파일 수정이나 명령이 어디까지 실행됐는지 먼저 확인한 뒤 이어가야 합니다. 구체적인 점검 순서는 Claude Code API Error 500·529 해결: 끊긴 작업을 중복 없이 재개하기에 정리되어 있습니다.

멈추고 신고할 시점과 첨부할 것

상태 페이지에 관련 공지가 없는데, 몇 분 간격으로 다시 보내고 다른 모델로 바꿔도 529가 계속된다면 더 이상 설정을 바꾸기보다 신고하는 편이 낫습니다.

• Claude Code 안에서 /feedback을 실행하면 대화 기록과 설명이 Anthropic에 전송되고, 미리 채운 GitHub 이슈를 열 수도 있습니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry 같은 서드파티 경로에서는 전송 대신 로컬 아카이브가 저장되므로, 그 파일을 Anthropic 계정 담당자에게 보내면 됩니다.
• 셸에서 claude doctor를 실행하면 설치 상태를 읽기 전용으로 진단하고, Claude Code 안의 /doctor는 설정 문제를 찾아 고쳐 줍니다.
• GitHub 이슈에서 같은 증상이 이미 보고됐는지 검색합니다.

신고할 때는 다음을 함께 남기면 재현과 분류가 빨라집니다.

• 마지막 문장까지 포함한 오류 전문. 끝 문장에 경로가 드러납니다.
• 발생 시각과 시간대
• 시도한 모델 목록과 fallback 전환 알림이 떴는지 여부
• /status에 표시된 활성 자격 증명
• claude --version 결과
• 게이트웨이를 쓴다면 메시지에 찍힌 호스트 이름. 이 경우 게이트웨이 운영 측에도 함께 알립니다.

자주 묻는 질문

몇 분 기다리면 풀리나요?

정해진 시간은 없습니다. 공식 문서도 "잠시 후" 또는 "몇 분 뒤" 다시 시도하라고만 안내합니다. 상태 페이지에 내 모델이 포함된 장애 공지가 있다면 해소 공지를 기준으로 판단하고, 그 사이에 작업을 이어가야 한다면 모델을 바꾸는 것이 현실적입니다.

fallback 모델로 넘어가면 비용이 달라지나요?

전환된 턴은 fallback 모델이 처리하므로, 사용량과 요금도 그 모델 기준으로 계산된다고 보면 됩니다. API 키나 클라우드 경로라면 모델마다 토큰 단가가 다르니 콘솔의 단가표를 확인하세요. 계정에 따라 사용량 크레딧으로 청구되는 모델(Fable 등)을 쓰려면 Claude Code가 먼저 확인을 요청합니다.

Claude Code가 아니라 내 코드에서 Claude API를 직접 호출하다 529가 나면요?

공식 SDK는 연결 오류, 요청 한도, 5xx를 기본 2회 자동 재시도하며 max_retries(TypeScript는 maxRetries)로 횟수를 바꿀 수 있습니다. 재시도 설계와 429 분기 처리는 Claude API 529 overloaded_error 처리법에서 개발자 관점으로 다룹니다.