최근 Claude API로 프로젝트를 하다가 각종 오류 때문에 머리가 아팠다. 며칠 동안 고생하면서 겪었던 문제들을 정리해 봤는데, 같은 고민을 하는 분들에게 도움이 되었으면 한다.
Error 401 Unauthorized
이 오류가 가장 흔한데, 십중팔구 API Key 문제다. Key가 완전히 복사됐는지 확인하고, 특히 앞부분의 sk-ant-가 빠지지 않았는지 체크하자. 또한 Key가 만료됐거나 취소(철회)된 경우에도 이 오류가 뜨니, Anthropic 관리자 페이지에서 새로 생성하면 된다.
Error 429 Rate Limit Exceeded
요청을 너무 자주 보내서 레이트 리밋(속도 제한)에 걸린 것이다. 무료 계정은 분당 60회만 요청할 수 있고, 유료 계정은 그보다 더 높다. 해결 방법:
- 코드에 지연을 추가하기(예: 요청마다 1초 간격)
- 재시도를 처리할 때 지수 백오프 전략 사용
- 계정 요금제를 업그레이드해 한도 상향
Error 529 Overloaded
Claude 서버가 과부하인 상태다. 이런 경우 몇 분 기다렸다가 다시 시도하면 된다. 자주 발생한다면 북미 시간대의 피크 시간을 피해 시간대를 분산해서 사용하는 것을 고려하자.


