API 키 권한 설정에서 첫 번째 막힘
Claude API를 처음 연동할 때 가장 먼저 막힌 부분은 API 키 권한 설정이었다. Anthropic 콘솔에서 API 키를 발급받았는데, 요청을 보내면 계속 401 Unauthorized 에러가 발생했다.
처음에는 헤더 설정 문제인 줄 알고 Authorization 부분을 여러 번 수정했다. Bearer 토큰 형식으로도 해보고, Basic Auth 형식으로도 시도해봤지만 해결되지 않았다.
결국 문제는 API 키에 할당된 크레딧이 없었던 것이었다. Anthropic 콘솔에서 결제 수단을 등록하고 최소 금액을 충전한 후에야 정상적으로 작동했다. 다른 AI API들과 달리 무료 티어가 없다는 점을 놓쳤다.
요청 형식 차이로 인한 파싱 에러
두 번째 문제는 요청 형식이었다. OpenAI API에 익숙해져 있어서 같은 형식으로 요청을 보냈는데, Claude API는 구조가 달랐다.
특히 메시지 형식에서 차이가 컸다. OpenAI는 ‘role’과 ‘content’ 필드를 사용하는데, Claude는 ‘human’과 ‘assistant’ 구분이 더 명확해야 했다. 처음에는 400 Bad Request 에러만 계속 받았다.
공식 문서를 다시 읽어보니 메시지는 반드시 ‘human’으로 시작해야 하고, ‘assistant’ 응답이 있다면 그 다음은 다시 ‘human’이어야 한다는 규칙이 있었다. 이 순서를 지키지 않으면 요청 자체가 거부된다.
결국 요청 전에 메시지 배열을 검증하는 함수를 추가해서 해결했다. 마지막 메시지가 ‘human’인지 확인하고, 홀수 번째는 ‘human’, 짝수 번째는 ‘assistant’가 되도록 구조를 맞췄다.
토큰 제한과 응답 처리 문제
세 번째 삽질은 토큰 제한 관련이었다. 긴 프롬프트를 보내면 갑자기 응답이 잘리거나 에러가 발생했다.
처음에는 max_tokens 파라미터를 높게 설정하면 될 줄 알았다. 하지만 입력 토큰과 출력 토큰을 합쳐서 모델별 최대 토큰 수를 넘으면 안 된다는 것을 늦게 깨달았다.
Claude-3-haiku는 상대적으로 토큰 제한이 있어서, 긴 문서를 분석할 때 문제가 생겼다. 입력 텍스트가 길면 출력할 토큰이 부족해져서 응답이 중간에 끊어졌다.
해결책은 입력 길이를 미리 체크하는 것이었다. 대략적인 토큰 수를 계산해서 제한을 넘으면 텍스트를 청크 단위로 나누어 여러 번 요청하도록 수정했다. 완벽한 토큰 계산은 아니지만 문자 수 기준으로 어림짐작해서 처리했다.
Make.com 연동에서 생긴 인코딩 문제
Make.com을 통해 Claude API를 호출할 때는 또 다른 문제가 있었다. 한글 텍스트가 포함된 요청을 보내면 응답이 깨져서 돌아왔다.
처음에는 Claude API 자체의 문제인 줄 알았다. 같은 요청을 Postman으로 직접 보내보니 정상적으로 작동했다. 문제는 Make.com의 HTTP 모듈에서 인코딩 처리 방식이었다.
Make.com의 HTTP 요청 모듈에서 Content-Type을 ‘application/json; charset=utf-8’로 명시적으로 설정했다. 그리고 한글이 포함된 텍스트는 미리 URL 인코딩을 해서 보내도록 수정했다.
하지만 이것도 완전한 해결책은 아니었다. 응답받은 텍스트를 다시 디코딩하는 과정에서 일부 특수문자가 여전히 깨졌다. 결국 중요한 한글 처리가 필요한 작업은 Make.com 대신 직접 서버에서 처리하도록 바꿨다.
비용 관리와 요청 제한 대응
마지막으로 예상보다 비용이 많이 나왔던 문제가 있었다. 테스트하면서 긴 문서를 반복적으로 보냈는데, 토큰당 과금이라는 것을 제대로 계산하지 못했다.
특히 Claude-3-opus는 성능이 좋지만 비용이 상당했다. 간단한 작업도 습관적으로 opus를 사용하다가 한 달 사용료가 예상보다 훨씬 높게 나왔다.
이후에는 작업 복잡도에 따라 모델을 구분해서 사용하도록 했다. 단순한 텍스트 요약이나 번역은 haiku, 복잡한 분석이나 코드 생성은 sonnet, 정말 어려운 작업만 opus를 사용한다.
또한 요청 빈도 제한도 고려해야 했다. Make.com 시나리오에서 연속으로 여러 요청을 보내면 rate limit에 걸렸다. 요청 사이에 1-2초 정도 지연을 추가해서 해결했다.
지금 돌이켜보면 공식 문서를 더 꼼꼼히 읽었어야 했다. 다른 API 경험에 의존해서 비슷할 것이라고 가정한 것이 삽질의 원인이었다. 새로운 API를 연동할 때는 처음부터 차근차근 문서를 읽는 것이 결국 더 빠른 길이다.