Claude API로 실제 서비스를 만들면 가장 먼저 부딪히는 벽이 에러 처리와 rate limit입니다. 첫 호출은 쉽지만, 트래픽이 늘면 429(rate limit)·529(overloaded) 같은 응답을 안정적으로 다루는 코드가 반드시 필요합니다. 이 글은 공식 에러 코드 체계와 재시도 전략을 정리합니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
HTTP 에러 코드 한눈에 보기
Claude API는 예측 가능한 HTTP 에러 코드 형식을 따릅니다. 응답 본문은 항상 JSON이며, 최상위 error 객체에 type과 message가 담기고, 추적용 request_id가 함께 옵니다. 공식 문서 기준 주요 코드는 다음과 같습니다.
400 invalid_request_error— 요청 형식·내용 문제. (목록에 없는 다른 4XX에도 사용될 수 있음)401 authentication_error— API 키 문제.402 billing_error— 결제·청구 정보 문제. Console에서 결제 정보 확인.403 permission_error— 해당 리소스 사용 권한 없음.404 not_found_error— 요청한 리소스를 찾을 수 없음.413 request_too_large— 요청이 최대 허용 바이트를 초과. (직접 API에서는 API 서버 도달 전 Cloudflare에서 반환)429 rate_limit_error— 계정이 rate limit에 도달.500 api_error— Anthropic 시스템 내부의 예기치 못한 오류.504 timeout_error— 처리 중 시간 초과. 긴 요청은 스트리밍 권장.529 overloaded_error— API가 일시적으로 과부하 상태.
재시도해야 할 에러 vs 고쳐야 할 에러
핵심은 어떤 에러를 재시도하고 어떤 에러를 재시도하지 말아야 하는지 구분하는 것입니다.
- 재시도 권장:
429,500,504,529— 일시적이거나 서버 측 요인. 백오프를 두고 재시도하면 성공할 수 있습니다. - 재시도 무의미(코드/설정 수정):
400,401,402,403,404,413— 같은 요청을 반복해도 같은 에러가 납니다. 요청 내용·키·권한·결제·크기를 고쳐야 합니다.
특히 529 overloaded_error는 전체 사용자 대상 고트래픽 상황에서 발생할 수 있고, 조직 사용량이 급증하면 가속(acceleration) 한도 때문에 429가 날 수도 있습니다. 공식 문서는 트래픽을 점진적으로 늘리고 일관된 사용 패턴을 유지할 것을 권고합니다.
지수 백오프 + 지터(jitter)
재시도 대상 에러를 만났을 때의 표준 패턴은 지수 백오프에 지터를 더하는 것입니다.
- retry-after 헤더 우선:
429응답에는 얼마나 기다려야 하는지 알려주는retry-after헤더가 포함됩니다. 이 값이 있으면 그만큼 대기하는 것이 가장 정확합니다. - 헤더가 없으면 지수 증가: 대기 시간을 1초 → 2초 → 4초 → 8초처럼 지수적으로 늘립니다.
- 지터 추가: 여러 클라이언트가 동시에 같은 간격으로 재시도하면 부하가 몰립니다. 무작위 지연(지터)을 더해 분산시킵니다.
- 최대 재시도 횟수 제한: 무한 재시도는 피하고 상한(예: 5회)을 둡니다.
참고로 Anthropic 공식 SDK(Python·TypeScript 등)는 기본적으로 일부 에러에 대해 자동 재시도 로직을 내장하고 있습니다. 직접 구현하기 전에 SDK 기본 동작을 먼저 확인하면 중복 작업을 줄일 수 있습니다.
SDK는 타입드 예외로 처리
공식 SDK는 raw JSON 대신 타입이 지정된 예외를 던집니다. 예를 들어 404는 Python에서 anthropic.NotFoundError, TypeScript·Go·Java 등 언어별로 클래스명이 다릅니다. 공식 문서는 에러 메시지 문자열을 매칭하지 말고 SDK의 타입 클래스를 잡으라고 권고합니다. 가장 구체적인 클래스부터 처리하는 것이 안전합니다.
요청 크기 한도 (413 예방)
413 request_too_large를 피하려면 엔드포인트별 최대 요청 크기를 알아야 합니다. 공식 문서 기준:
- Messages API — 32 MB
- Token Counting API — 32 MB
- Batch API — 256 MB
- Files API — 500 MB
긴 요청은 스트리밍/배치로
큰 max_tokens로 비스트리밍 요청을 오래 끌면 일부 네트워크가 유휴 연결을 끊어 타임아웃이 날 수 있습니다. 공식 문서는 10분을 넘길 수 있는 긴 요청은 스트리밍 Messages API나 Message Batches API를 쓰라고 안내합니다. 실제로 SDK는 비스트리밍 요청이 10분 타임아웃을 넘길 것으로 예상되면 이를 검증하고 TCP keep-alive 소켓 옵션을 설정합니다.
정리
안정적인 Claude API 연동의 핵심은 ① 에러 코드를 재시도 가능/불가로 분류, ② 429·5xx에는 retry-after 우선 + 지수 백오프·지터, ③ 4xx는 코드·설정 수정, ④ SDK 타입드 예외 활용, ⑤ 큰 요청은 스트리밍/배치입니다. 더 알아보려면 같은 사이트의 Claude API 시작하기와 Claude SDK 시작하기를 함께 참고하세요.
본 글은 Anthropic 공식 문서(platform.claude.com/docs)의 공개 정보를 바탕으로 정리했습니다. API 정책·한도·에러 코드는 변경될 수 있으니 실제 구현 시 공식 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.