Originally published at claudeguide.io/claude-api-error-529

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)

typescript
async function retryOverload<T