최근 개인 프로젝트인 KidStory의 메인 화면 이미지 히어로 교체 작업을 자동화했다. 10분 간격으로 트리거를 걸어두고 자동으로 이미지를 변경하는 쏠쏠한 재미를 느끼고 있었다. 하지만 어느 날 아침 메일함이 Google Apps Script(GAS)의 실행 실패 알림으로 가득 찬 것을 발견했다.
원인을 찾아보니 무료 티어로 사용 중이던 Gemini API의 일일 20회 한도를 초과하여 발생한 429 RESOURCE_EXHAUSTED 에러 때문이었다. 무료 할당량을 전부 소진하자마자 API 호출이 완전히 막히기 시작한 것이다. 가벼운 마음으로 처리해 둔 기존 재시도 로직이 오히려 상황을 악화시키고 있었다.
기존 재시도 로직이 불러온 참사
기존에는 네트워크 일시 오류나 일시적 과부하를 대비해 지수 백오프 방식의 재시도 로직을 설계해 두었었다. 에러가 발생하면 8초, 15초, 25초, 40초, 60초 간격으로 대기 시간을 늘려가며 총 150초 동안 최대 5번 재시도하도록 설정했다. 일반적인 일시적 과부하 상태라면 이 정도로 충분히 해결되었다.
하지만 일일 할당량 소진으로 발생한 429 에러는 초 단위로 아무리 대기해도 절대 해결되지 않는 성격의 에러였다. 결국 매 실행마다 무의미하게 150초의 재시도 예산을 끝까지 낭비하며 실패를 거듭했다. 이로 인해 GAS의 단일 실행 시간 제한인 6분을 매번 초과하여 스크립트가 강제 종료되는 심각한 리소스 낭비 현상이 반복되었다.
429는 다 같은 에러가 아니다
이 과정에서 가장 뼈아프게 깨달은 점은 동일한 429 RESOURCE_EXHAUSTED 응답이라도 그 원인에 따라 대응을 달리해야 한다는 사실이다. 몇 초 뒤에 다시 호출하면 무사히 풀리는 일시적 과부하성 429 에러와, 하루가 지나야 풀리는 일일 할당량 소진 에러를 확실히 구분해 처리해야 했다.
이를 구분하지 않고 획일적으로 재시도를 시도하면 소중한 실행 시간과 API 리소스만 갉아먹는 치명적인 원인이 된다. 예외 처리 로직을 더 꼼꼼하고 똑똑하게 가다듬어야 하는 이유를 직접 겪으며 뼈저리게 배울 수 있었다.
일일 한도 소진 감지와 자기정지 설계
우선 API 응답 바디의 내용을 정밀하게 분석했다. 확인해 보니 일일 한도 초과로 인한 에러 발생 시 응답 바디 안에 'PerDay'라는 일일 할당량 관련 quotaId 정보가 포함되어 반환되는 점을 찾을 수 있었다. 이 특정 키워드가 응답 바디에 존재할 경우에는 재시도를 전면 차단하고 즉시 포기하도록 분리했다.
여기에 멈추지 않고 배치 처리 프로세스도 자동 정지가 가능하도록 개선했다. 한도 초과가 감지된 순간 처리 중이던 남은 배치 항목들은 안전하게 대기 큐로 되돌려 보냈다. 그리고 반복해서 에러를 뿜어낼 10분 주기 자동 트리거 자체를 스스로 삭제하여 작동을 멈추도록 구현했다.
마지막으로 재개 시점을 정확히 파악할 수 있도록 상세 안내 로그를 출력했다. Gemini API의 일일 한도 리셋 기준인 태평양시 자정은 한국 시간으로 오후 4시에서 5시 사이이다. 이 시간을 로그에 명시하여 언제 트리거를 다시 살리면 되는지 직관적으로 기록해 관리 편의성을 높였다.
시행착오를 통해 배운 스마트한 에러 핸들링
무조건 에러가 난다고 해서 기계적으로 재시도를 돌리는 설계가 얼마나 큰 리소스 낭비를 부르는지 직접 겪으며 깨달았다. 에러의 세부 원인을 정교하게 발라내고 상황에 맞추어 유연하게 양보하고 동작을 멈추는 설계야말로 진정한 서비스 안정성을 지탱하는 근간이다. 이번 삽질을 계기로 백엔드 예외 처리의 완성도를 한 단계 끌어올릴 수 있었다.