에러 핸들링과 재시도, 안 깨지는 워크플로우의 조건

잘 굴러가던 워크플로우가 실무에 붙자마자 무너지는 이유는 대개 하나입니다. 외부 API는 가끔 500을 뱉고, 웹훅은 가끔 중복으로 오고, 데이터는 가끔 비어서 옵니다. 실패를 없앨 순 없습니다. 실패를 다루는 워크플로우를 만들 뿐이죠.

이 글은 데모에서 프로덕션으로 넘어가는 순간 반드시 손봐야 하는 네 가지 패턴을 다룹니다. Retry on Fail, Error Trigger, 멱등성 키, 데드레터. 이 네 개만 갖춰도 새벽에 슬랙 알림 받고 급하게 로그 뒤지는 일이 확 줄어듭니다.

1. 재시도부터 켜라 — 가장 싼 방어선

네트워크 호출이 있는 노드라면 Settings → Retry On Fail을 켜는 것만으로 일시적 오류의 70~80%가 사라집니다. HTTP 502, 타임아웃, DNS 실패 같은 것들이죠. 기본값은 3회, 1초 간격이지만 실무에선 지수 백오프를 흉내내서 간격을 벌려주는 게 낫습니다.

// HTTP Request 노드 설정 예시
{
  "retryOnFail": true,
  "maxTries": 4,
  "waitBetweenTries": 2000,   // 2s → 4s → 8s (수동으로 벌림)
  "continueOnFail": false
}

2. Error Trigger로 실패 전용 흐름을 만든다

재시도가 다 실패하면 어떻게 됩니까? 기본적으로는 워크플로우가 죽고 실행 로그에만 흔적이 남습니다. 아무도 안 봅니다. Error Trigger 노드로 별도 워크플로우를 만들어 두면, 실패한 순간 슬랙·이메일·PagerDuty로 즉시 통지할 수 있습니다.

1. 새 워크플로우 생성 → Error Trigger 노드 하나 배치
2. 실패 원본 워크플로우의 Settings → Error Workflow에서 방금 만든 것을 지정
3. Error Trigger 뒤에 Slack 또는 Email 노드 연결
4. 메시지 템플릿에 {{ $json.execution.url }}을 넣어 실행 상세로 바로 점프하게
5. 실패 데이터는 Postgres 노드로 failed_jobs 테이블에 적재

3. 멱등성 — 두 번 실행돼도 안전한가?

재시도가 만능은 아닙니다. 결제 API에 요청을 보냈는데 응답이 안 왔다고 다시 보내면 결제가 두 번 될 수 있습니다. 이메일 발송도 마찬가지죠. 같은 입력에 대해 같은 결과가 나오도록, 즉 멱등하게 만드는 게 핵심입니다.

가장 흔한 패턴은 요청마다 고유한 Idempotency-Key를 붙이는 겁니다. Stripe, Toss, Shopify 등 주요 결제/커머스 API가 이 헤더를 표준으로 지원합니다.

// HTTP Request 노드 Headers
{
  "Idempotency-Key": "{{ $json.orderId }}-{{ $now.toFormat('yyyyMMdd') }}"
}

// 서버 쪽에서 같은 키로 두 번 들어오면 첫 응답을 재사용

결제 API가 이 헤더를 지원하지 않는다면? 워크플로우 시작 지점에 Postgres 노드로 INSERT ... ON CONFLICT DO NOTHING을 심어서 이미 처리한 주문번호는 조용히 건너뛰게 만드세요.

4. 데드레터 — 실패 데이터를 버리지 마라

재시도도 실패하고 사람도 못 봤으면 그 데이터는 어디로 갑니까? 대부분 사라집니다. failed_jobs 같은 테이블 하나 만들어서 원본 payload, 실패 시각, 에러 메시지, 재시도 횟수를 남겨두세요. 나중에 원인을 고친 뒤 배치로 재처리할 수 있습니다.

• payload_json — 원본 요청/데이터 통째로
• error_message — n8n이 뱉은 에러의 첫 200자
• node_name — 어떤 노드에서 죽었는지
• retry_count — 몇 번 재시도했는지
• created_at, resolved_at — 발생 시각과 해결 시각

실제로 이렇게 만들었을 때

한 이커머스 고객사의 주문 → ERP 연동 워크플로우에 위 네 가지를 적용한 결과입니다. 도입 전 30일 vs 도입 후 30일 비교.

신뢰할 수 있는 워크플로우는 실패하지 않는 워크플로우가 아니라, 실패해도 티가 나고 되돌릴 수 있는 워크플로우입니다.— SynAct.ai 컨설팅팀

정리

완벽한 워크플로우는 없습니다. 대신 실패했을 때 30초 안에 알림이 오고, 데이터가 사라지지 않고, 원인을 고친 뒤 한 번의 재실행으로 복구되는 워크플로우는 만들 수 있습니다. 위 네 가지가 그 최소 조건입니다. 새 워크플로우를 프로덕션에 붙이기 전에 체크리스트로 삼으세요.