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

Claude API 503 service_unavailable: 원인과 해결법 (2026)

Claude API 503 service_unavailable는 Anthropic API가 일시적으로 응답 불가 상태에 발생합니다. 서비스 일시 중단이며, exponential backoff 재시도가 효과적해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

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

---

무엇을 의미하는가?

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

응답 예시:

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

---

흔한 원인 5가지

1. 전체 API 일시 장애 (status.anthropic.com 확인)
2. 특정 region/zone 부분 장애
3. Bedrock의 ProvisionedThroughput 한도 도달
4. Maintenance window (드물지만 사전 공지됨)

---

해결 코드 (Python)

# 503 + status page check
import time, requests, anthropic

def with_status_check(fn, max_retries=4):
    for attempt in range(max_retries):
        try:
            return fn()
        except anthropic.APIError as e:
            if e.status_code != 503 or attempt == max_retries - 1:
                raise
            # Optional: check Anthropic status page
            try:
                r = requests.get("https://status.anthropic.com/api/v2/status.json", timeout=3)
                indicator = r.json().get("status", {}).get("indicator")
                if indicator in ("major", "critical"):
                    print(f"⚠ status.anthropic.com: {indicator}. Backing off longer.")
                    time.sleep(180)
                    continue
            except Exception:
                pass
            time.sleep([5, 15, 30, 90][attempt])

해결 코드 (TypeScript)

typescript
async function with503Backoff<T