[고급] 504 타임아웃 에러, 구글링은 이제 그만. 웹훅 배관 터지기 전에 막는 법

결론부터 말한다. 간헐적으로 터지는 504 에러는 당신 탓이 아니다.

정확히는 당신의 자동화 시나리오나 Make, Zapier 같은 툴의 문제가 아니라는 의미다. 본질은 웹훅 요청을 받은 상대편 서버가 ‘처리 시간 초과’로 응답하지 못하는 것이다. 이걸 이해 못 하면 평생 구글링만 하다 끝난다. 시스템은 상호 약속이다. ‘이 시간 안에 답을 줘’라는 약속을 상대가 못 지킨 것 뿐이다.

웹훅은 초인종 같은 거다. 당신이 초인종(웹훅)을 누르면, 집주인(서버)이 나와서 ‘네, 받았습니다’(200 OK 응답)라고 대답해야 한다. 504 에러는 집주인이 너무 바쁘거나 아파서 대답이 없자, 기다리다 지친 당신이 그냥 가버리는 상황이다.

대부분의 사람들이 저지르는 치명적 실수 7가지

이 문제로 몇 날 며칠을 허비하는 사람들은 거의 예외 없이 아래 7가지 패턴 중 하나에 속한다.

1. 무지성 재시도

문제점: 에러가 나면 그냥 시나리오를 다시 실행한다. 상대 서버가 과부하로 힘들어하는데, 문을 더 세게 두드리는 격이다. 서버는 결국 다운되고, 당신의 IP는 블랙리스트에 오를 수도 있다.

해결책: ‘지수 백오프(Exponential Backoff)’ 로직을 적용해야 한다. 실패하면 1초, 그다음엔 2초, 4초, 8초… 대기 시간을 기하급수적으로 늘리면서 재시도하는 방식이다. 상대 서버에 숨 쉴 틈을 주는, 시스템 설계의 기본 예의다.

2. 동기식 처리 고집

문제점: 웹훅 하나로 데이터 수신, 처리, 결과 전송까지 모든 걸 끝내려 한다. 30초 안에 끝내야 할 미션을 10분짜리 대하드라마로 만드는 꼴이다. 웹훅의 타임아웃 제한은 보통 수십 초 내외로 매우 짧다.

해결책: 비동기(Asynchronous) 방식으로 전환해야 한다. 웹훅은 데이터를 받자마자 ‘OK, 접수 완료’라는 200 응답만 즉시 날리고 끝낸다. 실제 무거운 작업은 뒤에서 별도의 워크플로우가 처리하도록 파이프라인을 분리해야 한다.

3. 에러 핸들링의 부재

문제점: 에러가 나면 시나리오가 그냥 멈추거나, 무시하고 넘어가도록 방치한다. 데이터는 유실되고, 고객은 주문이 누락된 사실조차 모르게 된다. 이건 재앙이다.

해결책: 전용 에러 핸들링 경로를 설계해야 한다. 실패한 요청 데이터는 별도의 데이터 저장소(Data Store)나 구글 시트에 기록하고, 관리자에게 알림을 보낸다. 그리고 이 데이터들을 기반으로 수동 또는 자동 재처리를 시도해야 한다.

4. 타임아웃 설정에 대한 무지

문제점: 내가 쓰는 자동화 툴의 타임아웃이 몇 초인지, 상대방 API의 타임아웃은 몇 초인지 전혀 모른 채 시나리오를 짠다.

해결책: 양쪽 시스템의 공식 문서를 확인해서 타임아웃 제한을 명확히 인지해야 한다. 하지만 근본적인 해결책은 아니다. 결국엔 비동기 처리로 가야만 한다.

5. 무거운 응답 데이터

문제점: 웹훅이 성공적으로 작업을 마친 후, ‘성공했습니다’라는 단순 신호만 주면 되는데 굳이 처리 결과 데이터 전체를 응답(Response)에 담아 보낸다. 데이터가 클수록 응답 시간은 길어지고 타임아웃 확률만 높아진다.

해결책: 웹훅의 응답은 HTTP 200 상태 코드와 최소한의 확인 메시지로 끝내야 한다. 결과 데이터가 필요하다면, 나중에 별도의 API 호출로 가져오는 게 맞다.

6. 서버 로그 미확인

문제점: 무조건 자동화 툴이 문제라고 생각한다. 정작 불이 난 곳은 상대편 서버인데, 우리 집 소화기만 붙들고 있는 셈이다.

해결책: 요청을 받는 서버의 로그를 확인해야 근본 원인을 알 수 있다. 데이터베이스 쿼리가 느린 건지, 특정 로직에서 병목 현상이 생기는지 로그에 다 나와 있다.

7. 큐(Queue) 시스템의 부재

문제점: 요청이 들어오는 족족 실시간으로 처리하려 한다. 갑자기 요청이 100개 몰리면 서버는 그대로 뻗는다. 1인 식당에 손님이 한꺼번에 100명 들이닥친 것과 같다.

해결책: 중간에 큐(Queue)라는 대기열 시스템을 둬야 한다. 웹훅은 요청을 큐에 던져놓고 즉시 응답한다. 별도의 처리 시스템(Worker)이 큐에서 작업을 하나씩 꺼내 자신의 속도에 맞게 처리한다. 이게 대용량 트래픽을 다루는 시스템의 기본 구조다.

실전 우회 전략: 비동기식 재시도 파이프라인

이론은 끝났다. 실전 구조는 이렇다.

1. 시나리오 A (웹훅 수신용): 외부 요청을 받는다. 받은 데이터를 즉시 Make의 Data Store나 Airtable 같은 곳에 저장한다. 그리고 바로 ‘200 OK’ 응답을 보내고 종료한다. 이 시나리오는 1초 안에 끝나야 한다.
2. 데이터 저장소 (Queue 역할): ‘상태’ 컬럼을 만들어 ‘대기’, ‘처리중’, ‘성공’, ‘실패’ 등으로 관리한다. ‘재시도 횟수’ 컬럼도 필수다.
3. 시나리오 B (데이터 처리용): 1분마다 스케줄링으로 실행된다. 데이터 저장소에서 ‘대기’ 상태인 작업을 하나 가져온다. 실제 API 호출 등 무거운 작업을 수행한다.
4. 에러 처리: 시나리오 B가 실패하면, 데이터 저장소의 해당 작업 상태를 ‘실패’로 바꾸고 ‘재시도 횟수’를 1 늘린다. 3번 이상 실패하면 ‘영구실패’로 변경하고 관리자에게 슬랙/메일로 경고를 보낸다.

이 구조는 웹훅 요청과 실제 처리를 완벽하게 분리(Decoupling)한다. 한쪽 배관이 터져도 다른 쪽은 멀쩡하게 돌아간다. 이게 안정적인 파이프라인의 핵심이다.

이 구조조차 버겁다면, 시스템의 근본적인 설계부터 다시 봐야 한다. 현재 비공개로 빌드업중인 ‘파이프마스터 클럽’ 네이버 카페에서 더 깊은 논의를 진행 중이니, 관심 있다면 미리 탑승하는 것도 방법이다.

PipeMaster-Lab 운영정책 및 제보 안내