Claude API 529 overloaded_error: 원인과 해결법 (2026)

Claude API 529 overloaded_error는 Anthropic API가 전체적으로 과부하 상태일 때에 발생합니다. API 일시 과부하이며, exponential backoff 재시도가 효과적해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

529 HTTP 상태 코드는 Anthropic API가 전체적으로 과부하 상태일 때을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "overloaded_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "..."
  }
}

흔한 원인 5가지

1. 특정 모델에 트래픽 폭증 (모델 발표 직후 등)
2. 지역별 capacity 한계 도달
3. Long-running streaming 세션 다수

해결 코드 (Python)

# Overloaded errors deserve longer waits than rate limits
import time, anthropic

def retry_overload(fn, max_retries=5):
    waits = [5, 15, 30, 60, 120]
    for attempt in range(max_retries):
        try:
            return fn()
        except anthropic.APIError as e:
            if e.status_code != 529 or attempt == max_retries - 1:
                raise
            wait = waits[attempt]
            print(f"Overloaded. Waiting {wait}s...")
            time.sleep(wait)
    # Optional: fallback to a smaller model
    return fn_with_haiku()

해결 코드 (TypeScript)

async function retryOverload<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
  const waits = [5, 15, 30, 60, 120];
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (e: any) {
      if (e.status !== 529 || attempt === maxRetries - 1) throw e;
      await new Promise((r) => setTimeout(r, waits[attempt] * 1000));
    }
  }
  throw new Error("max retries exceeded");
}

529 vs 500 vs 503: 무엇이 다른가?

세 서버 에러를 혼동하지 않도록 비교합니다:

529가 발생할 때는 소형 모델 폴백이 가장 효과적인 대응입니다. claude-opus-4가 과부하 상태여도 claude-haiku-4-5는 대개 가용합니다. 핵심 사용자 기능에는 Haiku로 폴백하고, 비핵심 AI 기능은 큐에 넣어 과부하 해소 후 처리하는 전략을 추천합니다.

재시도 전략

이 에러는 재시도 가능합니다. Exponential backoff 권장 시퀀스:

attempt 1 → wait 5s
attempt 2 → wait 15s
attempt 3 → wait 30s
attempt 4 → wait 60s
attempt 5 → wait 120s (final)

응답 헤더의 retry-after가 있으면 그 값을 우선 사용하세요.

비용 영향

재시도 시 매번 input 토큰이 다시 청구됩니다. 재시도 횟수 × 입력 토큰 = 추가 비용. Prompt caching을 적용하면 재시도 비용을 90%까지 절감할 수 있습니다.

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

빠른 진단 체크리스트

529 발생 시 현황을 빠르게 파악하는 체크리스트:

• status.anthropic.com 에서 "Degraded Performance" 또는 "Partial Outage" 공지가 있는가?
• 특정 모델(예: claude-sonnet-4-5)에서만 발생하는가? 다른 모델(claude-haiku-4-5)로 폴백 가능한가?
• 현재 요청이 실시간 처리가 반드시 필요한가? 아니라면 Batch API로 큐에 넣어두는 것이 유리함
• 재시도 대기 시간을 429보다 길게(5초~2분) 잡고 있는가?
• 여러 요청이 동시에 과부하를 가중시키지 않도록 jitter를 추가했는가?

프로덕션 모니터링

529는 글로벌 과부하이므로, status.anthropic.com을 실시간 모니터링하고 과부하 구간에 신규 요청을 큐에 보관하는 전략이 효과적입니다:

import time, anthropic, logging
from collections import deque

logger = logging.getLogger("claude.overload")

class OverloadQueue:
    """529 구간 동안 요청을 큐에 보관하고 복구 후 재처리."""
    def __init__(self, client: anthropic.Anthropic):
        self.client = client
        self.queue = deque()
        self.overloaded_until = 0.0

    def submit(self, **kwargs):
        if time.time() < self.overloaded_until:
            logger.info("과부하 구간 — 큐에 추가")
            self.queue.append(kwargs)
            return None
        try:
            return self.client.messages.create(**kwargs)
        except anthropic.APIError as e:
            if e.status_code == 529:
                # 최소 30초 ~ 최대 120초 과부하 상태로 마킹
                self.overloaded_until = time.time() + 60
                logger.warning(
                    "529 overloaded_error — 60초간 큐 모드 전환",
                    extra={"queue_size": len(self.queue)}
                )
                self.queue.append(kwargs)
                return None
            raise

    def drain(self):
        """과부하 해소 후 큐 처리."""
        while self.queue and time.time() >= self.overloaded_until:
            kwargs = self.queue.popleft()
            self.submit(**kwargs)
            time.sleep(0.5)  # 드레인 중 재차 과부하 방지

언제 지원팀에 연락해야 하나요?

529는 Anthropic 인프라 문제이므로 개별 지원보다는 공식 상태 페이지를 모니터링하는 것이 효율적입니다. 다음 경우에만 문의하세요:

• status.anthropic.com에 장애 표시가 없는데 1시간 이상 529가 지속되는 경우
• Enterprise 또는 Tier 4 고객으로 SLA 위반 수준의 다운타임이 발생한 경우
• 특정 API key 또는 조직에서만 529가 반복되는 경우 (선택적 과부하 가능성)

관련 에러

• 400 invalid_request_error — 잘못된 요청 형식
• 401 authentication_error — 인증 실패
• 403 permission_error — 권한 부족
• 429 rate_limit_error — Rate limit 초과
• 529 overloaded_error — API 일시 과부하

자주 묻는 질문

529 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청은 청구되지 않습니다. 단, 재시도 후 성공한 요청은 정상 청구됩니다.

529와 다른 에러의 차이는?

529는 일시적/서버 측 이슈로 재시도가 효과적입니다. 반면 4xx 클라이언트 에러 (400/401/403/404)는 요청 자체에 문제가 있어 재시도해도 동일한 결과가 나옵니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

네, Anthropic의 error.type 명명 규칙은 모든 deployment (Direct API, AWS Bedrock, GCP Vertex AI)에서 동일합니다. 다만 HTTP 상태 코드는 platform 별로 wrapping되어 다를 수 있습니다 (예: Bedrock은 529을 ValidationException으로 wrap).

다음 단계

• 프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
• 비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
• 에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

에러 처리 패턴 30개 + Pydantic 검증 코드 — Claude API Cost Optimization 마스터클래스 ($59)에 retry 미들웨어, 비용 가드레일, 에러 알림 패턴 12편 포함.