Claude API로 실제 서비스를 만들면 가장 먼저 부딪히는 벽이 에러 처리와 rate limit입니다. 첫 호출은 쉽지만, 트래픽이 늘면 429(rate limit)·529(overloaded) 같은 응답을 안정적으로 다루는 코드가 반드시 필요합니다. 이 글은 공식 에러 코드 체계와 재시도 전략을 정리합니다.
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 공식 사이트가 아닙니다.