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

> Claude Code의 529 과부하 메시지는 최대 10회 자동 재시도 뒤에 뜨며 사용량 한도와 무관합니다. 급하면 /model로 모델을 바꾸고, 반복되면 fallback 체인을 설정하세요.

- URL: https://blog.laozhang.ai/ko/posts/claude-code-overloaded-error
- Published: 2026-04-11
- Updated: 2026-09-28
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude Code
- Tags: Claude Code, 529 에러, Overloaded, 과부하, fallbackModel, 문제 해결

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

```text
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 [오류 문서](https://code.claude.com/docs/en/errors)와 [모델 설정 문서](https://code.claude.com/docs/en/model-config#fallback-model-chains)에 적힌 내용입니다.

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

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

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

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

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

| 지금 상황 | 할 일 |
| --- | --- |
| 작업을 끊을 수 없음 | `/model`로 다른 모델로 전환. 데스크톱 앱은 모델 선택기 사용 |
| `Opus is experiencing high load, please use /model to switch to Sonnet`처럼 특정 모델을 짚는 메시지 | 메시지가 제안하는 모델로 전환 |
| 상태 페이지의 장애 제목에 지금 쓰는 모델 이름이 있음 | 제목에 없는 모델로 바꾸거나, 해소 공지가 올라올 때까지 대기 |
| 급하지 않음 | 몇 분 뒤 다시 전송 |
| 같은 주에 과부하로 여러 번 멈춤 | fallback 체인 설정 |
| CI, 스크립트, 원격 워커처럼 무인 실행 | `CLAUDE_CODE_RETRY_WATCHDOG=1` 설정 |
| 모델을 바꿔도 계속 529이고 상태 페이지에 공지가 없음 | `/feedback`으로 신고 |

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

![529 메시지를 본 뒤 상황별로 모델 전환, 몇 분 뒤 재전송, fallback 체인, CLAUDE_CODE_RETRY_WATCHDOG 설정, /feedback 신고 중 할 일을 고르는 표](https://blog.laozhang.ai/posts/ko/claude-code-overloaded-error/img/after-529-actions.webp)

## 내 경로의 상태 페이지 찾기

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

| 사용 경로 | 메시지 끝 문장이 가리키는 곳 |
| --- | --- |
| Claude 구독(Pro, Max, Team, Enterprise) 또는 Anthropic API 키 | `status.claude.com` |
| Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry | 해당 클라우드의 서비스 상태 페이지 |
| `ANTHROPIC_BASE_URL`로 지정한 게이트웨이 | 게이트웨이 호스트 이름 |

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

[status.claude.com](https://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가 요청을 실패시키지 않고 다음 모델로 넘어갑니다. 전환될 때는 알림이 표시됩니다.

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

```bash
claude --fallback-model sonnet,haiku
```

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

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

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

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

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

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

사람이 지켜보지 않는 실행에서는 529 한 번에 작업 전체가 실패하는 것이 가장 큰 손실입니다. 이럴 때 쓰는 것이 [`CLAUDE_CODE_RETRY_WATCHDOG`](https://code.claude.com/docs/en/env-vars)입니다.

```bash
# 과부하(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입니다.

```bash
export CLAUDE_CODE_MAX_RETRIES=3
```

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

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

| 화면 문구 | 뜻 | 다음 행동 |
| --- | --- | --- |
| `API Error: Request rejected (429)` | API 키, Bedrock 프로젝트, Google Cloud 프로젝트에 설정된 요청 한도에 도달. 조직 사용량을 갑자기 늘려도 429가 올 수 있음 | `/status`로 자격 증명 확인 후 [Claude Code Rate Limit Reached 해결: 사용량·컨텍스트·API 제한 구분하기](https://blog.laozhang.ai/ko/posts/claude-code-rate-limit-reached) |
| `API Error: Server is temporarily limiting requests (not your usage limit)` | 요금제 할당량과 무관한 짧은 제한. v2.1.199부터 자동 재시도 후 표시 | 잠시 뒤 재시도, 계속되면 상태 페이지 확인 |
| `API Error: 500 Internal server error` | API 내부의 예기치 않은 실패 | [Claude Code API Error 500 해결법](https://blog.laozhang.ai/ko/posts/claude-code-500-529-rate-limit) |
| `API Error: Server error mid-response. The response above may be incomplete.` | 응답 도중에 과부하나 5xx가 발생 | 아래 설명대로 실행된 작업부터 확인 |
| `Unable to connect to API`, `ECONNRESET` 등 | 네트워크나 프록시 문제 | [Claude Code Unable to connect to API 해결](https://blog.laozhang.ai/ko/posts/claude-api-error-connection-error) |

![진짜 529 과부하와 429 요청 한도, 짧은 요청 제한, 500 서버 오류, 응답 중간 끊김을 화면 문구, 뜻, 다음 행동으로 구분한 표](https://blog.laozhang.ai/posts/ko/claude-code-overloaded-error/img/529-lookalike-errors.webp)

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

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

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

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

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

- 마지막 문장까지 포함한 오류 전문. 끝 문장에 경로가 드러납니다.
- 발생 시각과 시간대
- 시도한 모델 목록과 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 처리법](https://blog.laozhang.ai/ko/posts/claude-api-error-529-overloaded)에서 개발자 관점으로 다룹니다.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-09-28.

- [오류 문서](https://code.claude.com/docs/en/errors) (code.claude.com)
- [모델 설정 문서](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [오류 문서](https://platform.claude.com/docs/en/api/errors) (platform.claude.com)
- [status.claude.com](https://status.claude.com/) (status.claude.com)
- [CLAUDE_CODE_RETRY_WATCHDOG](https://code.claude.com/docs/en/env-vars) (code.claude.com)
- [GitHub 이슈](https://github.com/anthropics/claude-code/issues) (github.com)