프로덕션에서 Claude API를 쓰다 보면 한도 초과(429)나 일시적 서버 과부하(529)를 만나게 됩니다. 신뢰성 있는 앱은 이런 상황을 예측하고 적절히 재시도합니다. 이 글은 주요 에러 코드, 429와 529의 차이, 그리고 재시도 전략을 공식 기준으로 정리합니다. (공식 문서: docs.claude.com/errors · 기준 시점: 2026년 6월)
주요 HTTP 에러 코드
공식 문서 기준으로 API는 예측 가능한 HTTP 에러 코드를 따릅니다.
400 invalid_request_error— 요청 형식·내용 문제(다른 4XX에도 쓰일 수 있음)401 authentication_error— API 키 문제402 billing_error— 결제·청구 정보 문제403 permission_error— 키에 해당 리소스 권한 없음404 not_found_error— 요청한 리소스 없음413 request_too_large— 요청이 허용 크기 초과(예: Messages API 32MB)429 rate_limit_error— 레이트리밋 초과500 api_error— Anthropic 내부의 예기치 못한 오류504 timeout_error— 처리 시간 초과(긴 요청은 스트리밍 권장)529 overloaded_error— API 일시적 과부하
에러는 항상 JSON으로 오며, error 객체에 type·message가 있고 추적용 request_id도 포함됩니다. 단 스트리밍(SSE)은 200 응답 이후 에러가 날 수 있어, 표준 처리와 다를 수 있습니다.
429 레이트리밋이란
Messages API의 한도는 분당 요청 수(RPM), 분당 입력 토큰(ITPM), 분당 출력 토큰(OTPM)으로 모델 클래스별로 측정됩니다. 한도를 넘기면 429와 함께 얼마나 기다릴지 알려주는 retry-after 헤더가 옵니다. anthropic-ratelimit-* 헤더로 어떤 한도가 걸렸는지 구분할 수 있습니다.
참고로 대부분의 모델에서 캐시된 입력 토큰은 ITPM에 포함되지 않습니다 — 프롬프트 캐싱이 실효 한도를 넓혀 주는 이유입니다(자세히는 비용 줄이기).
429와 529는 다릅니다
- 429(rate_limit_error) — 내 사용량이 한도를 넘은 것. 대응은 요청 속도를 늦추고
retry-after를 따르는 것. - 529(overloaded_error) — 서버 쪽 일시적 과부하로, 내 잘못이 아닙니다. 대응은 백오프 후 차분히 재시도하는 것.
증상이 비슷해 둘을 혼동하기 쉽지만 진단·대응 경로가 다릅니다. 지속되면 공식 상태 페이지(status.claude.com)에서 서비스 상태를 확인하세요.
재시도 전략
핵심은 지수 백오프 + 약간의 무작위(jitter)로, 최대 횟수까지만 재시도하는 것입니다. 429는 retry-after 값을 우선 따르고, 500·504·529는 점점 간격을 늘려 재시도합니다. 4xx 중 그 외(400·401·403·404 등)는 재시도 대신 요청·인증을 고쳐야 합니다.
import anthropic, time
client = anthropic.Anthropic()
def call_with_retry(**kwargs):
for attempt in range(5): # 최대 5회
try:
return client.messages.create(**kwargs)
except anthropic.RateLimitError: # 429
time.sleep(2 ** attempt) # 1s,2s,4s... (retry-after가 있으면 우선)
except anthropic.APIStatusError as e: # 500/504/529 등
if e.status_code in (500, 504, 529):
time.sleep(2 ** attempt)
else:
raise # 그 외 4xx는 즉시 수정 필요
raise RuntimeError("재시도 한도 초과")공식 SDK는 일부 전이성 오류를 자동으로 재시도하기도 합니다. 무한 재시도나 병렬 폭주는 오히려 상황을 악화시키니 피하세요.
한도에 덜 걸리는 법
- 점진적 증가 — 트래픽을 갑자기 올리면 가속(acceleration) 한도로 429가 날 수 있으니 서서히 늘리세요.
- 프롬프트 캐싱 — 캐시된 입력은 대체로 ITPM에 안 잡혀, 실효 처리량이 커집니다.
- 모니터링 — Claude Console의 Usage 페이지에서 한도 여유와 피크 사용을 확인하세요.
관련 가이드
첫 호출은 Claude API 시작하기, 긴 응답·타임아웃 대응은 스트리밍, 비용·캐싱은 비용 줄이기를 함께 보세요.
에러 코드·한도 수치·헤더 등 세부 사항은 변동될 수 있으며(공식 정책상 type 값은 늘어날 수 있음), 가장 정확한 정보는 공식 문서(docs.claude.com)에서 확인하시기 바랍니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.