Anthropic의 Claude 3.5 Sonnet은 압도적인 코딩 능력과 추론 능력으로 개발자들에게 필수적인 도구가 되었습니다. 하지만 실제 프로젝트에 API를 연동하다 보면 예상치 못한 에러 코드들을 마주하게 됩니다. 특히 ‘401 Unauthorized’나 ‘429 Rate Limit Exceeded’는 생산성을 가로막는 주범이죠. 2,000자 가이드를 통해 완벽하게 해결해 보겠습니다.
💡 팁: Claude API는 Tier 시스템(1~5단계)에 따라 사용량이 철저히 제한됩니다. 오류 발생 시 자신의 Tier가 몇 단계인지 먼저 확인하는 것이 급선무입니다.
1. 401 Unauthorized: 인증 및 API 키 오류
이 에러는 보통 API 키가 틀렸거나, 헤더 형식이 잘못되었을 때 발생합니다. 특히 환경 변수(Environment Variable)를 로드하는 과정에서 공백이 포함되는 실수가 빈번합니다.
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
anthropic-version: 2023-06-01
위와 같이 정확한 헤더 키와 값을 입력했는지, 그리고 계정 대시보드에서 해당 API 키가 활성화된 상태인지 다시 한번 체크하세요.
2. 429 Rate Limit Exceeded: 할당량 초과 해결
가장 흔한 오류입니다. 분당 요청 수(RPM) 또는 분당 토큰 수(TPM)가 제한을 넘었을 때 발생합니다.
- Exponential Backoff: 요청 실패 시 즉시 재시도하지 말고 대기 시간을 기하급수적으로 늘려가며 재시도 로직을 작성하세요.
- Tier 업그레이드: 계정에 일정 금액 이상을 충전하고 사용 실적을 쌓으면 상위 Tier로 자동 승급되어 한도가 늘어납니다.
- 토큰 절약: 불필요한 System Prompt를 줄이고 응답 길이를 제어(max_tokens)하여 TPM 소모를 최소화하세요.
3. 400 Overloaded Error: 서버 과부하
이는 사용자의 잘못이 아닌 Anthropic 본사 서버의 일시적인 과부하입니다. 이런 경우 스테이터스 페이지(status.anthropic.com)를 확인하고 잠시 대기하는 것이 최선입니다.
| 에러 코드 | 의미 | 즉시 조치 사항 |
|---|---|---|
| 401 | 인증 실패 | API 키 유효성 및 헤더 재확인 |
| 403 | 권한 없음 | 카드 결제 실패 또는 지역 제한 확인 |
| 429 | 요청 제한 | 요청 빈도 감소 및 지연 재시도 |
| 529 | 서버 부하 | 서버 안정화까지 대기 |