API 429 오류가 반복되면 워크플로우가 멈춥니다. n8n 공식 블로그(2026년 10월 30일)는 배치 요청·대기 노드·재시도·에러 워크플로우를 조합해 속도 제한을 워크플로우 안에서 직접 처리하는 방법을 설명합니다. 스로틀링과 속도 제한의 차이, Retry-After 헤더 활용법, 지수 백오프에 지터를 더하는 이유를 실무 설정 기준으로 정리합니다.
스로틀링과 속도 제한 — 무엇이 다른가
n8n 공식 블로그(2026년 10월 30일 게시)는 두 개념을 다음과 같이 구분합니다.
**속도 제한(Rate limiting)**: 정해진 기간 안에 요청 수가 상한을 초과하면 요청이 거부됩니다. 대부분의 경우 HTTP 429 Too Many Requests 응답이 반환됩니다.
**스로틀링(Throttling)**: 초과 요청을 거부하는 대신 큐에 넣거나 지연시킵니다. 워크플로우 입장에서는 오류 대신 느린 응답이 돌아옵니다.
공식 설명에서 "API 공급자가 트래픽 정책을 제어하고, 소비자인 당신은 워크플로우가 어떻게 반응할지를 제어한다"고 명시합니다.
실용적인 차이는 다음과 같습니다. 속도 제한 상황에서는 429 오류를 받으면 워크플로우가 언제 재시도할지 직접 결정해야 합니다. 스로틀링 상황에서는 오류 대신 응답이 늦어지므로 이후 단계가 해당 응답에 의존한다면 지연을 계획해야 합니다.
- 속도 제한: 초과 요청 거부(429) — 워크플로우가 재시도 타이밍 결정
- 스로틀링: 초과 요청을 큐/지연 — 워크플로우는 오류 대신 느린 응답을 받음
- 제어 주체: API 공급자가 정책을 시행, 워크플로우 개발자가 대응 방식 결정
- 두 상황 모두 워크플로우 안에 대응 로직이 필요함
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
429 오류와 Retry-After 헤더 활용
공식 블로그에 따르면 API가 속도 제한을 초과했을 때 HTTP 429(Too Many Requests) 응답을 반환하며, 응답에 Retry-After 헤더가 포함될 수 있습니다.
공식 설명에서 "Retry-After가 있으면 재시도 타이밍을 추측하는 대신 해당 값을 사용하라"고 명시합니다.
Retry-After 헤더가 없는 경우에는 워크플로우가 자체적으로 재시도 간격을 결정해야 합니다. 이때 지수 백오프(exponential backoff)를 사용합니다.
**지수 백오프 동작 방식(공식 설명)**:
– 요청 실패 후 즉시 재시도하지 않고 대기 시간을 점진적으로 늘립니다.
– 예: 1초 → 2초 → 4초 → 8초
– 최대 대기 시간과 재시도 횟수를 설정해 일시적인 API 문제가 무한 재시도로 이어지지 않도록 합니다.
공식 설명에서 "즉시 같은 요청을 재시도하면 같은 문제를 반복할 수 있다"고 명시합니다.
- Retry-After 헤더가 있으면 해당 값 사용 — 추측 금지
- Retry-After 없으면 지수 백오프(1초→2초→4초→8초)로 간격 설정
- 최대 대기 시간과 재시도 횟수 상한 설정 필수 — 무한 재시도 방지
- 즉각 재시도는 같은 제한을 다시 만날 가능성이 높음 (공식 명시)
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
지터(Jitter) — 지수 백오프만으로 부족한 이유
공식 블로그는 지수 백오프만으로는 여러 워크플로우가 동시에 실패한 경우 문제가 재현된다고 명시합니다.
공식 설명에서 "함께 실패한 여러 워크플로우가 동시에 재시도할 수 있다. 각 지연에 약간의 무작위성(지터)을 더하면 시도를 분산해 또 다른 트래픽 급증을 방지한다"고 명시합니다.
지터 없는 지수 백오프는 재시도가 여전히 같은 시간대에 몰릴 수 있어 트래픽 급증이 재현됩니다. 지터를 추가하면 각 워크플로우가 약간 다른 시간에 재시도하므로 부하가 분산됩니다.
**AI 에이전트 도구 호출에서의 주의사항(공식 명시)**: 공식 블로그에서 "지터 추가는 LLM 도구 호출을 사용하는 AI 에이전트 시스템에서 특히 중요하다"고 명시합니다. LLM 도구 호출에서 오류가 발생하면 재시도가 가능한지, 에스컬레이션이 필요한지를 먼저 판단해야 합니다.
**부작용(side effects)이 있는 요청 주의사항(공식 명시)**: "부작용이 있는 요청은 의도치 않게 두 번 실행될 수 있으므로 자동 재시도 전에 API가 멱등성(idempotency)을 지원하는지 확인하라"고 명시합니다.
- 지수 백오프만으로는 동시 실패 워크플로우의 재시도가 몰릴 수 있음
- 지터(무작위 지연)를 추가하면 재시도를 분산해 트래픽 급증 재현 방지
- AI 에이전트 LLM 도구 호출: 재시도 가능 여부 먼저 판단 후 재시도 또는 에스컬레이션
- 부작용 있는 요청: 자동 재시도 전 멱등성 지원 여부 반드시 확인 (공식 명시)
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
n8n에서 요청 사전 페이싱 — 배치와 대기 노드
공식 블로그에 따르면 429 오류에 대응하는 것보다 사전에 요청을 조절해 제한에 걸리지 않는 것이 우선입니다. 공식 설명에서 "예측 가능한 제한이 있는 API는 복구보다 예방이 대부분 더 낫다"고 명시합니다.
**HTTP Request 노드의 배치 처리(공식 명시)**:
– Items per Batch: 한 번에 처리할 항목 수 설정
– Batch Interval: 다음 배치를 보내기 전 대기 시간 설정
– 이 두 옵션으로 요청이 한꺼번에 나가는 것을 방지합니다.
**Loop Over Items + Wait 노드 조합(공식 명시)**:
– Loop Over Items 노드로 들어오는 항목을 배치 단위로 처리합니다.
– 루프 안에 HTTP Request 노드와 Wait 노드를 추가해 개별 요청 간 간격을 조절합니다.
– 공식 설명에서 "더 세밀한 제어가 필요할 때 이 조합을 사용하라"고 안내합니다.
**동시 실행 수 제한(공식 명시)**:
– 동시 실행(Concurrency) 제어로 여러 워크플로우가 동시에 같은 API를 호출하는 상황을 제한합니다.
– 공식 설명에서 "여러 워크플로우가 집합적으로 같은 API를 압도하지 않도록 병렬 실행을 제한하라"고 명시합니다.
- HTTP Request 노드: Items per Batch + Batch Interval으로 사전 페이싱
- Loop Over Items + Wait 노드: 개별 요청 간 세밀한 간격 제어
- Concurrency 제한: 여러 워크플로우가 동시에 같은 API를 호출하지 않도록 설정
- 사전 페이싱이 우선, 재시도와 에러 처리는 제한에 걸렸을 때의 안전장치
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
Retry on Fail 설정 — 실패 후 자동 재시도
공식 블로그에 따르면 사전 페이싱만으로는 모든 429를 막을 수 없습니다. 이 경우를 위해 n8n은 Retry on Fail 기능을 제공합니다.
**Retry on Fail 설정 방법(공식 명시)**:
– 노드 설정에서 Retry on Fail을 활성화합니다.
– Wait Between Tries: 재시도 간 대기 시간을 설정해 즉시 같은 요청을 보내지 않도록 합니다.
공식 설명에서 "이렇게 하면 실패한 노드를 자동으로 재시도하고, 즉시 같은 요청을 다시 보내지 않도록 Wait Between Tries를 설정할 수 있다"고 명시합니다.
**고급 재시도 로직(공식 명시)**:
– 더 복잡한 케이스(시도마다 대기 시간을 늘리는 지수 백오프 등)는 워크플로우 자체에 재시도 로직을 구성할 수 있습니다.
– 이렇게 하면 재시도 시점과 재시도 중단 시점을 직접 제어할 수 있습니다.
**사람이 확인해야 할 지점**: 부작용이 있는 요청(데이터 쓰기, 트랜잭션 등)은 자동 재시도가 의도치 않은 중복 실행을 일으킬 수 있습니다. API의 멱등성 지원 여부를 먼저 확인한 후 재시도를 활성화해야 합니다.
- Retry on Fail 활성화 + Wait Between Tries로 기본 재시도 설정
- Wait Between Tries: 즉시 재시도를 방지하는 대기 시간 설정
- 고급 지수 백오프: 워크플로우 자체에 재시도 로직 구성으로 간격 단계별 제어 가능
- 부작용 있는 요청: 멱등성 확인 후 재시도 활성화 — 중복 실행 위험 사전 점검 필수
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
에러 워크플로우로 지속 실패 처리 — Error Trigger 노드
공식 블로그에 따르면 재시도를 모두 소진한 후에도 실패하는 요청이 발생합니다. 이런 지속 실패를 실행 기록에만 남기는 대신 별도의 복구 경로로 라우팅할 수 있습니다.
**Error Trigger 노드 사용법(공식 명시)**:
– 전용 에러 처리 워크플로우를 별도로 만들고 Error Trigger 노드를 시작점으로 설정합니다.
– 다른 워크플로우가 실패하면 Error Trigger 노드가 해당 에러 워크플로우를 실행합니다.
공식 설명에서 "지속적인 429 오류가 정의된 복구 경로를 트리거할 수 있고, 실행이 조용히 끝나는 대신 로깅, 알림, 기타 복구 단계를 실행할 수 있다"고 명시합니다.
**에러 워크플로우에서 처리할 수 있는 것**:
– 실패 로깅(Slack 알림, 데이터베이스 기록)
– 담당자에게 알림 전송
– 수동 검토를 위한 실패 항목 보관
– 특정 오류 유형에 따른 분기 처리
**누락/중복 처리**: 에러 워크플로우가 실패한 항목을 별도 저장소에 기록해 두면, 이후 수동 또는 자동으로 재처리할 수 있습니다. 아무 처리 없이 실행 기록에만 남기면 실패 항목이 조용히 사라집니다.
- Error Trigger 노드: 다른 워크플로우 실패 시 별도 에러 처리 워크플로우 자동 실행
- 에러 워크플로우: 로깅·알림·복구 단계를 정의된 경로로 처리
- 지속 실패 항목을 실행 기록 외 별도 저장소에 기록 — 이후 재처리 가능
- 재시도 소진 후 지속 실패는 반드시 에러 워크플로우로 라우팅 권장 (공식 명시)
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
속도 제한 알고리즘 유형과 API별 확인 방법
공식 블로그는 API가 어떤 알고리즘으로 속도를 제한하는지에 따라 최적 대응이 달라진다고 명시합니다.
**고정 윈도우(Fixed window)**: 정해진 시간 구간으로 요청을 카운트합니다. 구간 경계에서 요청이 몰리는 버스트가 발생할 수 있습니다.
**슬라이딩 윈도우(Sliding window)**: 직전 N초 동안의 요청 수를 지속 측정합니다. 타이머가 초기화될 때까지 기다리는 방식이 통하지 않습니다.
**토큰 버킷(Token bucket)**: 토큰이 일정 속도로 충전되고 요청마다 소비됩니다. 미사용 토큰이 쌓이면 단기 버스트가 허용됩니다.
**누수 버킷(Leaky bucket)**: 요청이 큐에 들어가 일정 속도로 처리됩니다. 버스트가 고른 흐름으로 변환됩니다.
공식 설명에서 "모든 API가 같은 요청 패턴에 유리하지는 않다. 얼마나 공격적으로 배치하거나 페이싱할지 결정하기 전에 공급자의 속도 제한 문서를 확인하라"고 명시합니다.
이 정보는 n8n에서 Items per Batch, Batch Interval, Wait 노드의 값을 API별로 조정할 때 직접 적용됩니다.
- 고정 윈도우: 구간 경계 버스트 위험, 슬라이딩 윈도우: 타이머 초기화 대기 전략 불가
- 토큰 버킷: 미사용 토큰 누적으로 단기 버스트 허용 — 배치 처리에 유리
- 누수 버킷: 버스트를 고른 흐름으로 변환 — 일정 간격 페이싱이 효과적
- 각 API의 알고리즘을 먼저 확인 후 n8n 노드 값 조정 (공식 권장)
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
누가 이 설정을 써야 하는가
공식 블로그에 따르면 이 설정이 필요한 환경과 적합한 대응 방식은 다음과 같습니다.
**이 설정이 필요한 경우**:
– 외부 API를 대량으로 호출하는 n8n 워크플로우를 운영 중인 팀
– 429 오류가 반복 발생해 워크플로우가 중단되는 경우
– AI 에이전트 워크플로우에서 LLM 도구 호출이 속도 제한에 걸리는 경우
– 여러 워크플로우가 같은 API를 동시에 호출하는 환경
**n8n Cloud와 셀프 호스팅 모두 해당**: 공식 블로그에서 소개하는 Loop Over Items, HTTP Request 노드, Wait 노드, Error Trigger 노드는 n8n Cloud와 셀프 호스팅 모두에서 사용 가능한 기본 기능입니다.
**비용 고려사항**: 재시도를 과도하게 설정하면 API 호출 비용이 늘어납니다. 최대 재시도 횟수를 설정하고, 지속 실패는 에러 워크플로우로 라우팅해 불필요한 반복 호출을 방지해야 합니다.
**권장 접근 순서(공식 명시)**: 먼저 배치·대기 노드로 사전 페이싱을 설정하고, 그다음 재시도를 안전망으로 구성하고, 마지막으로 지속 실패에 대한 에러 라우팅을 추가합니다.
- 외부 API 대량 호출·AI 에이전트 LLM 도구 호출·다중 워크플로우 동시 호출 환경에 해당
- Loop Over Items, HTTP Request, Wait, Error Trigger 노드: Cloud·셀프 호스팅 모두 기본 제공
- 과도한 재시도는 API 호출 비용 증가 — 최대 재시도 횟수 설정 및 에러 라우팅으로 제한
- 권장 순서: 사전 페이싱 → 재시도 안전망 → 에러 워크플로우 라우팅 (공식 명시)
근거: Throttling vs. Rate Limiting: Backoff Strategies for Workflows – n8n Blog
자료 확인 기준
2026년 10월 31일에 공식 원문을 확인했습니다. 확인일과 정책·공연의 시행일은 다를 수 있으며 변경 공지는 원문을 우선합니다.
답글 남기기