n8n 2.47.0부터 관리자가 공개 API 키별로 읽기·쓰기 요청 한도를 직접 설정할 수 있습니다. 여러 팀이 하나의 인스턴스를 공유할 때 하나의 워크플로우가 전체 인스턴스를 차단하는 문제를 방지하며, 429 응답에 Retry-After 헤더가 포함돼 클라이언트가 재시도 타이밍을 정확히 알 수 있습니다. Cloud와 셀프 호스팅 모두 지원합니다.
이 기능이 해결하는 문제
n8n 공식 블로그(2026년 11월 13일 게시, 작성자 Andrea Saez)에 따르면 여러 팀이 하나의 n8n 인스턴스를 공유하면 공개 API가 여러 사람이 동시에 의존하는 공유 자원이 됩니다.
공식 설명에서 "A node runs once for each item, so a list of 1,000 items sends about 1,000 requests at once. Without per-key controls, one workflow like that can block everyone else on the instance"라고 명시합니다.
이 문제로 인해 일부 고객이 n8n 외부에 별도 속도 제한기를 직접 구축해 왔다고 공식 블로그에 명시합니다. 2.47.0부터는 이 보호 기능이 n8n 내부에 포함됩니다.
공식 설명에서 "Rate limits give admins that protection inside n8n, without building a separate rate limiter. Each team gets room to build, and the instance stays protected when one workflow runs away."라고 명시합니다.
- n8n 노드·HTTP Request 노드: 항목 수만큼 요청을 한꺼번에 발송 → 1,000개 항목 = 약 1,000회 요청 (공식 명시)
- 키별 제어 없이는 하나의 워크플로우가 같은 인스턴스의 다른 팀을 차단 가능
- 일부 고객이 외부에 별도 속도 제한기를 구축해 대응해 왔음 (공식 명시)
- 2.47.0부터 별도 도구 없이 n8n 내부에서 직접 설정 가능
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
공개 API 속도 제한이 작동하는 방식
공식 블로그에 따르면 속도 제한은 각 API 키가 인스턴스에 보낼 수 있는 트래픽에 상한을 설정합니다.
**읽기·쓰기 분리**: 읽기와 쓰기에 각각 별도 한도를 설정할 수 있으며, 전체 엔드포인트 기준과 엔드포인트별 기준 두 가지 모두 지원합니다. 쓰기에 더 엄격한 한도를 설정할 수 있습니다.
**API 키별 독립 카운트**: 각 API 키는 한도 내에서 독립적인 카운트를 가집니다.
**429 응답과 헤더**: 한도에 도달하면 n8n이 429 응답과 함께 Retry-After, rate-limit 헤더를 반환합니다. 공식 설명에서 "clients know when to retry and how many requests they have left, and can slow down before they reach the limit"라고 명시합니다.
**멀티 메인 환경**: 공식 설명에서 "In multi-main setups, every main shares one count per API key through Redis, so an API key that reaches its limit gets a 429 from every main until the window ends."라고 명시합니다. 멀티 메인에서도 Redis를 통해 하나의 카운트를 공유합니다.
- 읽기·쓰기 한도 분리, 전체 엔드포인트 기준 + 엔드포인트별 기준 모두 설정 가능
- API 키마다 독립 카운트 — 한 키의 한도 도달이 다른 키에 영향 없음
- 429 응답: Retry-After + X-RateLimit-Remaining + X-RateLimit-Reset 헤더 포함
- 멀티 메인: Redis로 모든 메인이 API 키별 카운트를 공유 (공식 명시)
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
속도 제한 활성화 방법 — 세 가지 경로
공식 블로그에 따르면 속도 제한은 기본적으로 비활성화 상태이며, 세 가지 방법으로 활성화할 수 있습니다.
**1. 설정 페이지(UI)**:
– Settings > Policies > Public API Limits 이동
– 'Enable API key rate limits' 활성화
– 한도와 윈도우 조정
– 'Enable limits' 선택
**2. 공개 API**:
– `GET /api/v1/settings/rate-limits`로 현재 설정 조회
– `PUT /api/v1/settings/rate-limits`로 설정 교체
– API 키에 `securitySettings:manage` 스코프 필요
**3. 환경 변수(셀프 호스팅)**:
– `N8N_PUBLIC_API_RATE_LIMIT_ENABLED`를 `true`로 설정 후 n8n 재시작
– `N8N_PUBLIC_API_RATE_LIMIT_*` 변수로 개별 한도와 윈도우 변경
공식 블로그에서 "Changes in the settings page or through the API apply immediately, without a restart."라고 명시합니다. 단, 환경 변수 설정은 재시작이 필요하며, 환경 변수가 설정되면 설정 페이지에서 해당 항목이 잠금 상태로 표시됩니다.
- 기본값: 비활성화 — 관리자가 직접 활성화해야 적용
- UI 변경·API 변경: 즉시 적용(재시작 불필요)
- 환경 변수 변경: 재시작 필요, 설정 페이지에서 잠금 상태로 표시
- securitySettings:manage 스코프가 없는 API 키로는 설정 조회·변경 불가
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
API 클라이언트와 워크플로우에서 한도 내에 머무는 방법
공식 블로그에 명시된 클라이언트 측 대응 방법입니다.
**API 클라이언트용 4가지 습관(공식 명시)**:
1. 429 수신 후 Retry-After에 명시된 초 수만큼 대기 후 재시도
2. 여러 클라이언트의 재시도가 분산되도록 최대 5초의 무작위 지연(지터) 추가
3. `X-RateLimit-Remaining`을 모니터링하고 0에 근접하면 `X-RateLimit-Reset` 시간까지 속도 낮추기
4. 대량 작업은 윈도우 전반에 걸쳐 일정한 속도로 분산
**n8n 워크플로우에서 자신의 인스턴스 API를 호출하는 경우(공식 명시)**:
– n8n 노드와 HTTP Request 노드는 항목마다 한 번씩 요청을 보내고 429에서 실패합니다.
– Batching 설정 추가: n8n 노드는 Request Options의 Batching, HTTP Request 노드는 Options의 Batching
– Items per Batch와 Batch Interval(ms) 설정
– 공식 예시: "Five items each second sends 300 requests a minute, which is below every default limit."
공식 블로그에서 "Batching works better here than Retry On Fail, which waits at most 5 seconds between tries and often retries inside the same window."라고 명시합니다. Retry On Fail은 같은 윈도우 안에서 재시도할 가능성이 높아 속도 제한 환경에서는 Batching이 더 효과적입니다.
- 429 후 Retry-After 준수 + 무작위 지터(최대 5초) 추가로 재시도 분산
- X-RateLimit-Remaining 모니터링: 0에 근접하면 X-RateLimit-Reset까지 속도 감소
- n8n 노드·HTTP Request 노드: Retry On Fail 대신 Batching 설정 권장 (공식 명시)
- 초당 5개 항목 = 분당 300회 요청 → 모든 기본 한도 이하 (공식 예시)
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
멱등성 키로 안전한 재시도 구성
공식 블로그에 따르면 속도 제한으로 429가 발생하면 클라이언트가 재시도해야 하는데, POST 요청을 재시도할 때 첫 번째 요청이 이미 성공했다면 중복 실행 위험이 있습니다.
공식 설명에서 "Idempotency keys make those retries safe, so clients can back off after a 429 and try again with confidence."라고 명시합니다.
**멱등성 키 작동 방식(공식 명시)**:
– 공개 API POST 요청에 `Idempotency-Key` 헤더 포함
– 요청 성공 시: n8n이 응답을 12시간 저장. 같은 키와 본문으로 재시도하면 저장된 응답 반환(POST 재실행 없음)
– 요청 실패 시: n8n이 키를 해제. 재시도가 정상적으로 실행
멱등성 키는 n8n 2.45.0부터 사용 가능합니다. 속도 제한(2.47.0)과 함께 쓰면 429 발생 → 백오프 → 재시도의 전체 흐름이 안전하게 구성됩니다.
공식 블로그에서 POST 요청을 사용하는 경우 속도 제한 활성화와 함께 멱등성 키를 추가하도록 권장합니다.
- Idempotency-Key 헤더: POST 요청 재시도 시 중복 실행 방지
- 성공한 요청 응답: 12시간 저장, 같은 키+본문 재시도 시 저장 응답 반환
- 실패한 요청: 키 자동 해제, 재시도가 정상 실행
- 멱등성 키: n8n 2.45.0 이상 / 속도 제한: n8n 2.47.0 이상
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
자주 묻는 질문 — 공식 FAQ 정리
공식 블로그에 명시된 FAQ 항목입니다.
**속도 제한 카운트에 포함되는 요청은?**
`/api/v1`에서 API 키를 사용하는 요청만 카운트됩니다. n8n 에디터에서의 요청은 포함되지 않습니다. 각 API 키는 독립 카운트를 가지며, 모든 키는 동일한 한도 내에서 작동합니다.
**특정 통합에 더 많은 여유를 주고 싶다면?**
공식 설명에서 "Run that integration on a separate n8n instance. Every API key in an instance shares the same limits, while each key keeps its own count, so a separate instance is the way to give one integration different limits."라고 명시합니다. 현재 버전에서는 같은 인스턴스 내에서 키별로 다른 한도를 설정하는 기능은 없습니다.
**한도를 낮추면 진행 중인 요청은?**
새 한도는 즉시 적용됩니다. 현재 카운트가 새 한도를 초과하면 해당 키의 다음 요청이 429를 받고, 윈도우가 종료되면 카운트가 초기화됩니다.
**특정 한도 유형만 비활성화하려면?**
해당 한도를 0으로 설정합니다. 읽기·쓰기, 전체·엔드포인트별을 개별로 끌 수 있습니다. 단, 속도 제한이 활성화된 상태에서 최소 하나의 한도는 0 이상이어야 합니다.
- 에디터 요청은 카운트 미포함, /api/v1 + API 키 요청만 집계
- 키별 다른 한도 설정 불가 — 별도 인스턴스로 분리해야 (공식 명시)
- 한도를 낮추면 즉시 적용, 초과 카운트 키는 윈도우 만료 시 초기화
- 속도 제한 활성화 시 최소 한 개의 한도는 반드시 0 초과
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
가용성·버전·비용
공식 블로그에 명시된 가용성 정보입니다.
**버전**: n8n 2.47.0 이상 필요
**플랜**: 모든 플랜에서 사용 가능 (공식 명시: "available on every plan")
**환경**: n8n Cloud와 셀프 호스팅 모두 지원
**멀티 메인**: Redis가 필요합니다. 멀티 메인 환경에서 Redis를 통해 API 키별 카운트를 모든 메인 인스턴스가 공유합니다.
**멱등성 키**: n8n 2.45.0 이상에서 사용 가능
추가 비용은 공식 블로그에 명시되지 않았으며, 속도 제한 자체는 n8n 플랜 비용 이외의 별도 요금이 없는 것으로 설명됩니다. 정확한 플랜별 조건은 n8n 공식 가격 페이지에서 확인이 필요합니다.
**시작 방법(공식 권장)**:
1. n8n 2.47.0 이상으로 업데이트
2. Settings > Policies > Public API Limits에서 속도 제한 활성화
3. API 속도 제한 공식 문서에서 전체 설정 옵션 확인
4. POST 요청을 사용하는 경우 멱등성 키 함께 적용
- n8n 2.47.0 이상 필요, 모든 플랜 지원, Cloud·셀프 호스팅 모두 지원
- 멀티 메인 환경: Redis 필요 — 모든 메인이 API 키별 카운트 공유
- 멱등성 키: n8n 2.45.0 이상, 속도 제한과 함께 적용 권장
- 별도 추가 비용: 공식 블로그 미명시 — n8n 공식 가격 페이지 확인 필요
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
누가 이 설정이 필요한가
공식 블로그에서 명시하거나 설명에서 도출할 수 있는 적합한 사용 조건입니다.
**지금 설정이 필요한 경우**:
– 여러 팀이 하나의 n8n 인스턴스를 공유하는 조직 — 하나의 워크플로우가 다른 팀 작업을 차단하는 위험을 방지
– 1,000개 이상 항목 목록을 처리하는 워크플로우가 있는 경우 — n8n 노드·HTTP Request 노드가 항목마다 요청 발송
– 현재 n8n 외부에 별도 속도 제한기를 구축해 운영 중인 팀 — n8n 내부 기능으로 대체 가능
– n8n 공개 API를 외부 클라이언트나 CI/CD 파이프라인에서 호출하는 환경
**멀티 메인 환경에서 추가 확인 필요**:
– Redis 설정이 되어 있어야 API 키별 카운트 공유가 작동합니다.
**이 설정이 필요 없는 경우**:
– 단일 사용자 또는 단일 팀만 인스턴스를 사용하고 대량 요청 워크플로우가 없는 경우
– n8n 에디터에서만 작업하고 공개 API를 외부에서 호출하지 않는 경우 (에디터 요청은 한도에 포함되지 않음)
- 여러 팀이 인스턴스를 공유하는 조직: 즉시 활성화 권장
- 대량 항목 처리 워크플로우: Batching 설정 병행 필수
- 외부 별도 속도 제한기를 운영 중인 팀: n8n 내부 기능으로 대체 가능
- 멀티 메인: Redis 설정 확인 후 활성화
근거: New in n8n: Public API rate limits that keep every team on your instance running – n8n Blog
자료 확인 기준
2026년 11월 14일에 공식 원문을 확인했습니다. 확인일과 정책·공연의 시행일은 다를 수 있으며 변경 공지는 원문을 우선합니다.
답글 남기기