Apps Script에서 API 실패 로그를 남기는 방법

Apps Script에서 API 실패 로그를 남기는 방법에 대해 초보자도 이해할 수 있도록 핵심만 정리한 글입니다.

구글 시트 API 연동, 왜 자꾸 중간에 멈출까?

구글 시트 데이터를 읽어와 외부 서비스로 보내거나, 반대로 외부 데이터를 시트로 가져오는 작업을 구축해 두면 업무가 정말 편해집니다. Apps Script 자동화를 처음 설정했을 때는 모든 게 잘 작동하는 것 같지만, 며칠 지나지 않아 예상치 못한 문제에 부딪히곤 합니다.

잘 돌아가던 스크립트가 어느 날 갑자기 멈춰있고, 수백 개의 데이터 중 어디까지 처리되었는지 알 수 없어 난감했던 경험이 있을 겁니다. 외부 API를 호출할 때는 네트워크 지연, 잘못된 데이터 입력, 상대 서버의 일시적 오류 등 다양한 이유로 에러가 발생합니다. 이때 스크립트가 그대로 뻗어버리지 않게 만들고, 어떤 데이터 때문에 실패했는지 구글 시트에 차곡차곡 남겨두는 작업이 반드시 필요합니다.

에러가 나도 스크립트를 멈추지 않게 하는 핵심 옵션

기본적으로 구글 앱스 스크립트에서 UrlFetchApp.fetch 함수를 사용해 API를 호출할 때, 상대방 서버에서 404(찾을 수 없음)나 500(서버 에러) 같은 에러 상태 코드를 반환하면 스크립트는 그 즉시 빨간색 에러 메시지를 뿜으며 강제 종료됩니다. 100개의 데이터를 처리해야 하는데 3번째에서 에러가 나면 나머지 97개는 시도조차 못 하는 것이죠.

이 현상을 막으려면 API를 호출할 때 muteHttpExceptions 옵션을 true로 설정해야 합니다. 이 옵션을 켜두면 서버에서 에러를 뱉어내더라도 스크립트가 강제로 멈추지 않습니다. 대신 에러 응답 자체를 하나의 결과물로 받아오게 됩니다. 우리는 이 결과물을 확인해서 성공인지 실패인지 판단하고, 실패했을 때만 따로 로그를 남기는 방식으로 로직을 짜면 됩니다.

안정적인 Apps Script 자동화를 위한 로그 기록 단계

실제 스크립트 흐름은 보통 시트에서 데이터를 읽어온 뒤 반복문을 돌며 API를 호출하는 식입니다. 이때 실패한 건들만 따로 모아볼 수 있는 로그 전용 시트 탭을 하나 만들어 두는 것이 좋습니다.

1. 전체 로직을 try-catch로 감싸기

API 호출 옵션을 잘 주더라도, JSON 데이터를 파싱하다가 오류가 나거나 구글 서버 자체의 네트워크 단절 등 예측 불가능한 치명적 오류가 발생할 수 있습니다. 반복문 내부를 try-catch 블록으로 감싸두면, 어떤 종류의 에러가 나더라도 스크립트가 튕기지 않고 안전하게 다음 데이터로 넘어갈 수 있습니다.

2. 응답 상태 코드 확인하기

API 호출 후에는 getResponseCode 함수를 사용해 상태 코드를 확인해야 합니다. 보통 200번대 코드가 나오면 성공입니다. 하지만 400(우리가 보낸 파라미터가 잘못됨), 429(너무 짧은 시간에 많이 호출함), 500(상대방 서버 문제) 등 200이 아닌 숫자가 나온다면 실패로 간주하고 분기 처리를 해야 합니다.

3. 구글 시트에 상세한 에러 기록 남기기

실패로 판명 났다면 SpreadsheetApp을 이용해 로그 전용 시트에 appendRow 함수로 새로운 행을 추가합니다. 이때 기록해야 할 필수 항목은 현재 시간, 상태 코드, API가 반환한 에러 메시지 본문, 그리고 가장 중요한 ‘내가 요청했던 데이터의 식별자’입니다. 예를 들어 고객 번호나 이메일 주소를 함께 적어두어야 나중에 어떤 데이터에서 문제가 생겼는지 바로잡을 수 있습니다.

초보자가 흔히 놓치는 주의사항

Apps Script 자동화를 처음 다루는 분들이 에러 처리를 할 때 자주 하는 실수들이 있습니다. 이 부분만 주의해도 유지보수 시간이 절반으로 줄어듭니다.

• Logger.log만 믿고 창 닫기: 에러를 확인할 때 Logger.log나 console.error만 사용하는 경우가 많습니다. 테스트할 때는 괜찮지만, 시간 주도형 트리거로 새벽에 알아서 돌아가게 해 두었다면 나중에 그 로그를 다시 찾기 매우 힘듭니다. 영구적인 기록을 원한다면 반드시 구글 시트 셀에 직접 텍스트를 찍어내야 합니다.
• 요청 데이터 누락: 에러 메시지만 시트에 남겨두면 “잘못된 요청입니다”라는 문구만 수십 줄 쌓이게 됩니다. 도대체 어떤 데이터를 보냈길래 잘못되었다는 건지 알 길이 없습니다. 로그를 남길 때는 반드시 API로 쏘아 보냈던 핵심 파라미터를 함께 시트에 기록하세요.
• 무작정 JSON.parse 시도하기: API가 실패했을 때 상대 서버가 친절하게 JSON 형태로 에러 이유를 알려주기도 하지만, 서버가 완전히 뻗었을 때는 쌩뚱맞은 HTML 에러 페이지를 텍스트로 던지기도 합니다. 이걸 그대로 JSON.parse 하려고 하면 파싱 에러가 나면서 스크립트가 멈춥니다. 응답 텍스트를 파싱하기 전에 구조를 확인하거나, 파싱 자체도 try-catch로 보호해야 합니다.

현실적인 마무리 조언

처음부터 에러가 나면 3번 다시 시도하고, 그래도 안 되면 관리자에게 이메일을 보내는 식의 복잡한 재시도 로직을 짤 필요는 없습니다. 일단은 실패한 건들이 구글 시트에 한 줄도 빠짐없이 예쁘게 쌓이도록 만드는 것부터 시작해 보세요. 쌓인 로그를 눈으로 보면서 원인을 하나씩 고쳐나가는 것이 훨씬 효율적입니다.

또한, 구글의 Apps Script 자동화 작업은 한 번 실행될 때 최대 6분까지만 동작한다는 제한이 있습니다. 데이터가 너무 많거나 에러 처리 과정에서 시간을 너무 많이 지체하면 6분 제한에 걸려 스크립트가 강제 종료될 수 있으니 이 점을 항상 염두에 두어야 합니다. 실패 로그 시트는 주기적으로 비워주거나 처리 완료 표시를 해두어 쾌적하게 관리하는 습관을 들이시길 권합니다.