매일 아침 일과를 시작하기 전, 자동으로 세상의 트렌드를 요약해 주는 나만의 IssueLog 자동발행 시스템이 있다. 몇 달 동안 아무 문제 없이 조용히 제 역할을 하던 이 녀석이 최근 들어 이상한 조짐을 보이기 시작했다. 매일 새벽 4시에 발송되던 자동 발행이 실패했다는 알림이 오더니, 정작 오전 7시나 10시에 수동으로 트리거를 실행하면 또 멀쩡하게 성공하는 것이었다. 일정한 패턴도 없이 간헐적으로 발생하는 에러 때문에 아침마다 머리를 싸매야 했다.
로그를 확인해 보니 원인은 싱겁게도 외부 LLM API 호출 과정에서 발생한 404 에러였다. 구체적으로는 잘 쓰고 있던 models/gemini-2.5-flash 모델을 호출할 때 서버를 찾을 수 없다는 응답이 돌아오고 있었다. 왜 어떤 시간대에는 성공하고 어떤 시간대에는 실패하는지 처음에는 도무지 이해할 수 없었다. 이 의문을 풀기 위해 공식 가이드를 뒤져보며 본격적인 원인 분석에 들어갔다.
새벽 4시의 경고음, 간헐적 404 에러의 원인
원인을 파헤쳐 보니 바로 Gemini deprecation, 즉 모델 단종 절차 때문이었다. 구글은 구버전 모델을 한 번에 중단하지 않고 단계적으로 서비스 요청을 차단하는 유예기간 롤아웃 방식을 적용하고 있었다. 올해 10월 중순 완전히 종료되는 일정을 앞두고, 특정 시간대나 일부 요청에 대해 고의로 404 에러를 반환하며 개발자들에게 경고를 보내고 있었던 것이다. 새벽 4시의 실패와 아침 시간대의 성공은 결국 구글이 보낸 점진적 단종 신호였다.
문제를 인지했으니 당장 해결해야 했다. 하지만 내 시스템은 구글 앱스 스크립트(GAS) 기반으로 총 4개의 독립적인 프로젝트에 API 호출 로직이 흩어져 있었다. 소스코드를 열어보는 순간 눈앞이 아찔해졌다. 부끄럽게도 모든 코드 안에 models/gemini-2.5-flash라는 문자열이 고스란히 하드코딩되어 박혀 있었기 때문이다. API 주소를 하나씩 찾아다니며 수정해야 하는 비효율적인 상황을 마주하게 되었다.
하드코딩된 모델명을 상수로 일괄 분리하기
더 이상 미룰 수 없다는 생각에 즉시 리팩토링에 착수했다. 가장 먼저 수행한 작업은 모델명 상수 관리 구조를 도입하는 것이었다. 각 스크립트 상단에 GEMINI_MODEL이라는 전역 상수를 정의하고, 모든 API 호출부에서 이 상수를 참조하도록 코드를 변경했다. 이렇게 하면 앞으로 또 다른 LLM API 모델 단종 대응 상황이 발생하더라도 상수의 값 하나만 바꾸면 되기 때문에 유지보수가 극적으로 쉬워진다.
상수 분리를 마치고 기존의 단종 대상 모델 대신 최신 버전인 gemini-3.5-flash로 모델명을 이전했다. 다행히 이번 마이그레이션은 비용 부담이 없었다. Gemini 3.5-flash 역시 기존 무료 티어인 분당 10회(10 RPM), 하루 1,500회(1500 RPD) 제한 조건이 그대로 유지되었기 때문이다. Pro 모델과 달리 Flash 모델은 여전히 무료로 쓸 수 있어서 결제 카드를 등록하거나 유료 전환을 거치지 않고도 깔끔하게 이전을 완료했다. 준비된 4개의 GAS 프로젝트 모두에 이 상수화 작업과 모델 업그레이드를 적용해 주었다.
API 404 재시도에 대한 고찰과 교훈
이번 삽질을 통해 시스템 안정성에 대한 중요한 교훈을 얻었다. 보통 외부 API가 일시적으로 실패할 것에 대비해 API 404 재시도 로직을 설계해야 하는지 고민할 때가 있다. 네트워크 불안정이나 일시적인 서버 과부하로 인한 5xx 에러, 혹은 429 Rate Limit 에러는 백오프 알고리즘을 적용한 재시도가 매우 유용하다. 하지만 이번처럼 모델 단종으로 인한 404 에러는 자원이 완전히 사라졌음을 의미하므로 재시도를 해봤자 리소스만 낭비할 뿐이다.
따라서 에러 핸들링 코드를 작성할 때 404 응답은 절대 재시도 대상이 아님을 다시 한번 명확히 정의하고 코드를 가다듬었다. 또한 서비스의 핵심 동력인 외부 API의 모델명은 절대로 코드 깊숙한 곳에 직접 작성해서는 안 된다는 기본을 뼈저리게 느꼈다. 이번 대대적인 상수화 작업 덕분에 앞으로 구글이 또 어떤 모델을 갑작스럽게 단종시키더라도 몇 초 만에 의연하게 대처할 수 있는 단단한 코드 구조를 갖추게 되었다.