Claude Code 529 Overloaded: 원인, 재시도 설정, 해결 방법

Wokey Team · 2026-09-24

짧은 답: 529는 업스트림 모델이 지금 용량이 부족하다("overloaded", 과부하)는 뜻입니다. 잔액, 할당량, API 키와는 아무 관계가 없습니다. Claude Code는 오류를 보여 주기 전에 이미 여러 번 재시도했습니다. 용량은 모델별로 관리되므로 가장 빠른 해결책은 /model로 모델을 바꾸는 것입니다. 급하지 않다면 몇 분 기다렸다가 다시 보내세요.

정확한 오류 문구

Claude Code에서는 다음과 같이 표시됩니다.

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.

Claude Code 문서는 이 오류에 대해 세 가지를 설명합니다.

• 모든 사용자가 함께 겪는 일시적인 용량 문제입니다.
• Claude Code는 이 오류를 보여 주기 전에 여러 번 재시도했습니다.
• 529는 사용량 한도가 아니며 할당량에서 차감되지 않습니다.

ANTHROPIC_BASE_URL로 게이트웨이를 통해 연결하면 마지막 문장에 status.claude.com 대신 게이트웨이 호스트 이름이 표시됩니다.

Wokey에서 529가 생기는 곳

Wokey는 529를 직접 만들지 않습니다. 이 상태는 항상 업스트림 모델에서 옵니다. Wokey는 세 단계로 처리합니다.

1. 업스트림이 과부하를 알리면(예: Anthropic의 overloaded_error) Wokey는 먼저 같은 모델의 다른 업스트림 경로로 요청을 재시도합니다. 이 과정은 사용자에게 보이지 않습니다.

2. 재시도한 경로도 과부하일 때만 Wokey가 업스트림 상태를 그대로 전달합니다. HTTP 상태는 529로 유지되고, 본문은 Wokey의 표준 오류 형식이며 message에는 업스트림 자체의 문구가 들어갑니다.

   {"error":{"code":"upstream_overloaded","message":"Overloaded","type":"invalid_request_error"}}
   

3. 응답 스트리밍이 시작된 뒤에 과부하가 발생하면 HTTP 529가 아니라 스트림 내 error 이벤트로 전달됩니다.

따라서 Wokey를 통해 받은 529는 같은 모델의 여러 업스트림 경로가 동시에 과부하였다는 뜻이며, 보통 제공업체 쪽 피크 시간에 일어납니다. 이 응답에는 Retry-After 헤더가 없으며, 클라이언트는 자체 백오프 일정에 따라 재시도합니다.

다른 오류와 구분하기

"업스트림이 바쁘다"는 뜻은 529와 503뿐입니다. 나머지는 사용자 쪽에서 조치가 필요합니다.

해결 방법

1. 기다렸다가 다시 보내세요. 과부하는 대개 몇 분 안에 풀리며, 짧은 급증은 Claude Code의 자동 재시도가 이미 처리합니다.

2. /model로 모델을 바꾸세요. 용량은 모델별로 관리되므로 Opus가 과부하일 때도 Sonnet은 잘 동작하는 경우가 많습니다. 세션에서 /model을 실행해 다른 모델을 고르면 되며, 다시 시작할 필요는 없습니다.

3. 무인으로 돌리는 긴 작업은 더 끈질기게 재시도하세요. ~/.claude/settings.json의 env 블록에 다음을 추가합니다.

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1을 설정하면 Claude Code가 429와 529 오류를 무제한으로 재시도하며, 시도 간격을 최대 5분까지 늘립니다. 밤새 돌려 두는 작업에 적합합니다.
• 몇 번만 더 시도하려면 대신 CLAUDE_CODE_MAX_RETRIES를 설정하세요. 기본값은 10이고 최대 15입니다.

4. 직접 작성한 코드에서는 529 재시도 여유를 두세요. 공식 Anthropic SDK는 529를 포함한 5xx 오류를 기본적으로 두 번 재시도합니다. 배치 작업이라면 max_retries를 늘리고 호출을 지수 백오프로 감싸세요.

Codex에서 529가 보일 때

Codex는 529를 포함한 5xx 오류를 재시도 가능한 오류로 취급합니다.

• HTTP 계층은 기본적으로 4번 재시도합니다(제공업체의 request_max_retries).
• 이어서 스트림 계층이 최대 5번 더 재시도합니다(stream_max_retries).
• 모두 실패하면 오류는 unexpected status 529로 시작하고 그 뒤에 응답 본문이 이어집니다.

그 본문의 code가 upstream_overloaded라면 위에서 설명한 업스트림 과부하입니다. 해결 방법도 같습니다. 기다리거나 config.toml에서 모델을 바꾸세요. Codex 전체 설정은 Codex config.toml 가이드를 참고하세요.