API 속도 제한과 워크플로 안정화
API 속도 제한이 실패한 워크플로를 의미할 필요는 없습니다. 제한이 어떻게 작동하는지, 그리고 재시도, 배치 처리, 스마트한 속도 조절로 429 오류를 어떻게 다룰 수 있는지 알아보세요.
10개 레코드에서는 잘 작동하는 워크플로가 10,000개에서는 반드시 잘 작동한다고 볼 수는 없습니다. API 호출을 많이 할수록, 그 API는 더 자주 속도를 늦추라고 알려올 것입니다.
이것이 바로 API 속도 제한의 핵심입니다. 서비스는 트래픽을 관리하고 인프라를 보호하기 위해 특정 기간 동안의 요청 수를 제한합니다.
하지만 제한에 걸린다고 해서 반드시 실행이 실패해야 하는 것은 아닙니다. 적절한 접근 방식만 있다면 워크플로를 망치지 않고도 API 속도 제한 안에서 작업할 수 있습니다. 이 가이드에서 그 방법을 보여드립니다.
API 속도 제한이란 무엇이며 어떻게 작동하나요?
API 속도 제한은 클라이언트가 일정 기간 동안 보낼 수 있는 요청 수의 상한선을 정합니다. 어떤 API는 분당 100개의 요청을 허용하는 반면, 다른 API는 일일 할당량을 사용하거나 호출하는 엔드포인트에 따라 요청을 제한하기도 합니다.
이러한 제한은 한 클라이언트가 자원 몫 이상을 소모하지 않도록 하면서 API가 트래픽을 관리하는 데 도움이 됩니다. 그 방식은 API마다 다릅니다. 어떤 API는 짧은 폭주를 허용하고, 다른 API는 더 안정적인 요청 흐름을 목표로 합니다.
일반적인 속도 제한 알고리즘
대부분의 속도 제한은 몇 가지 일반적인 알고리즘을 기반으로 합니다.
- 토큰 버킷: 요청은 시간이 지나면서 채워지는 버킷의 토큰을 사용합니다. 충분한 토큰을 모아두었다면, 즉시 제한에 걸리지 않고 한꺼번에 여러 요청을 보낼 수 있습니다.
- 누수 버킷: 요청은 큐에 들어가 일정한 속도로 처리됩니다. 한꺼번에 폭주하는 요청을 허용하는 대신 갑작스러운 급증을 완화합니다.
- 고정 윈도우: 요청 수를 정해진 구간 동안 집계합니다. 예를 들어 오후 2:00부터 2:01까지 100개의 요청을 세는 방식입니다. 다음 윈도우가 시작되면 카운터가 초기화됩니다.
- 슬라이딩 윈도우: 고정된 경계에서 초기화하는 대신, API는 이동 중인 기간을 되돌아보며 집계해 고정 윈도우 초기화 시점에 생길 수 있는 트래픽 급증을 방지합니다.
속도 제한 응답 헤더와 429 계약
API가 어떤 알고리즘을 사용하는지 정확히 알 필요는 없는 경우가 많습니다. 중요한 것은 API가 현재 상태를 어떻게 알려주는지입니다.
일부 API는 요청 허용량이나 제한이 언제 초기화되는지를 보여주는 헤더를 반환합니다. 제한을 초과하면 표준 응답은 429 Too Many Requests입니다. Retry-After 헤더가 있으면 다시 시도하기 전에 얼마나 기다려야 하는지도 알려줄 수 있습니다.
자동화된 워크플로에서는 이런 신호가 유용한 지침이 됩니다. 모든 429를 예상치 못한 실패로 처리하는 대신, API가 제공하는 정보를 활용해 언제 계속 진행해도 안전한지 판단할 수 있습니다.
API 속도 제한 알고리즘을 선택하는 방법
직접 API 제한기를 만들고 있다면, 하나의 “최선”의 알고리즘은 없습니다. 적절한 선택은 예상되는 트래픽과, API 뒤에 있는 서비스에 갑작스러운 요청 폭주가 얼마나 큰 문제가 되는지에 따라 달라집니다.
일반적인 접근 방식을 나란히 비교하면 장단점이 더 분명해집니다.
토큰 버킷과 누수 버킷 비교
두 알고리즘 모두 요청량을 제어하지만, 폭주를 다루는 방식은 다릅니다.
토큰 버킷은 시간이 지나면서 처리 용량을 쌓아갑니다. 사용할 수 있는 토큰이 충분하다면 클라이언트는 여러 요청을 한꺼번에 소비할 수 있어, 짧은 폭주가 허용되는 상황에 적합합니다. 누수 버킷은 반대 방식입니다. 요청을 일정한 속도로 처리해, 서비스에 도달하기 전에 급증을 완화합니다.
따라서 선택 기준은 시스템이 어느 정도의 변동성을 견딜 수 있는지에 달려 있습니다. 토큰 버킷은 폭주를 허용하고, 누수 버킷은 더 예측 가능한 요청 속도를 선호합니다.
고정 윈도우와 슬라이딩 윈도우 비교
고정 윈도우는 단순합니다. 정해진 기간 동안 요청 수를 세고, 그다음 카운터를 초기화하면 됩니다. 문제는 초기화 시점 주변에서 발생합니다. 한 윈도우의 끝에서 할당량을 모두 사용하고, 다음 윈도우의 시작에서 또다시 모두 사용할 수 있어 갑작스러운 급증이 생길 수 있습니다.
슬라이딩 윈도우는 연속적으로 움직이는 기간 동안 요청을 측정해 이런 강제 초기화를 피합니다. 덕분에 최근 트래픽을 더 정확하게 파악할 수 있지만, 추적하는 데 더 많은 작업이 필요합니다.
단순함이 가장 중요하다면 고정 윈도우로도 충분할 수 있습니다. 요청량을 더 엄격하게 제어해야 한다면 슬라이딩 윈도우가 일반적으로 더 적합합니다.
대규모 환경에서의 API 속도 제한 모범 사례
알고리즘을 고르는 것은 일의 일부일 뿐입니다. API가 성장하면 모든 클라이언트나 엔드포인트에 같은 제한을 적용하는 것이 거의 적절하지 않습니다. 또한 그 제한을 이해하기 쉽게 만들고, 여전히 의도한 대로 작동하는지 계속 살펴봐야 합니다.
클라이언트와 엔드포인트에 따라 제한을 설정하세요
복잡한 데이터베이스 쿼리를 유발하는 요청은 캐시된 응답을 가져오는 요청보다 더 많은 비용이 듭니다. 마찬가지로 유료 고객은 무료 플랜을 시험해 보는 사람보다 더 많은 용량이 필요할 수 있습니다.
단계별 제한을 두면 모든 요청에 같은 상한을 적용하는 대신 이런 차이를 반영할 수 있습니다. 소비하는 리소스와 예상되는 트래픽에 따라 엔드포인트, 클라이언트, 요금제별로 서로 다른 임계값을 설정할 수 있습니다.
제한을 명확하게 하세요
속도 제한은 예상치 못한 일이 되어서는 안 됩니다. 제한이 무엇인지 문서화하고, 클라이언트가 그 제한에 가까워지거나 초과했을 때 유용한 정보를 반환하세요.
응답 헤더를 통해 클라이언트에게 남은 용량이나 제한이 언제 초기화되는지를 알려줄 수 있습니다. 429 Too Many Requests 응답을 반환한다면, 가능하면 Retry-After 헤더를 포함해 클라이언트가 언제 다시 시도해야 하는지 알 수 있게 하세요.
트래픽이 변하면 제한도 다시 검토하세요
오늘 잘 맞는 제한이 6개월 뒤에도 적절하리라는 보장은 없습니다. 트래픽 패턴은 변하고, 인프라는 확장되며, 제품이 발전하면서 일부 엔드포인트는 더 비싸질 수 있습니다.
클라이언트가 얼마나 자주 제한에 걸리는지, 그리고 갑작스러운 요청 증가가 API 뒤의 시스템에 부담을 주고 있는지 모니터링하세요. 그러면 임계값을 조정해야 할 때 참고할 실제 사용 데이터를 얻을 수 있습니다.
API 속도 제한을 존중하는 워크플로우 만들기
다른 사람의 API를 호출할 때, 속도 제한은 여러분이 정할 수 없습니다. 대신 그 제한에 걸렸을 때 자동화가 어떻게 동작할지는 여러분이 정할 수 있습니다.
n8n 에서는 이런 동작을 워크플로우 자체에 넣을 수 있습니다. n8n은 엔지니어링 팀이 AI 에이전트와 에이전틱 시스템을 만드는, 소스 공개형 AI 네이티브 워크플로우 자동화 플랫폼입니다. 요청이 한꺼번에 몰려 실행 실패로 끝나게 두는 대신, 요청을 얼마나 빨리 보낼지와 API가 기다리라고 했을 때 무엇을 할지를 제어할 수 있습니다.
즉시 재시도하지 말고 Retry-After를 따르세요
API가 429를 반환하면 같은 요청을 곧바로 다시 보내는 것은 보통 상황을 더 악화시킵니다. 먼저 응답 헤더를 확인하세요. API가 Retry-After를 제공하면, 이를 사용해 워크플로우가 다시 시도하기 전에 얼마나 기다려야 하는지 결정하세요.
n8n 은 재시도 로직을 처음부터 다시 만들지 않고도 API 속도 제한을 처리할 수 있는 몇 가지 방법을 제공합니다. 더 단순한 경우에는 Retry On Fail를 사용해 실패한 노드를 설정한 대기 시간 후에 다시 시도할 수 있습니다. 다음 요청을 언제 보낼지 더 세밀하게 제어해야 한다면 Loop Over Items 와 Wait nodes 도 사용할 수 있습니다.
재시도 정책을 모두 소진한 뒤에도 API가 계속 요청을 거부한다면, 에러 워크플로우를 통해 실패를 처리할 수 있고 긴 실행 로그 속에 묻히지 않게 할 수 있습니다.
루프 안에서 지수적 백오프 메커니즘을 구현할 수도 있습니다. wait node 는 더 긴 시간 동안 일시 중지하여 반복 횟수를 줄여줍니다.
한계에 도달하기 전에 속도를 낮추세요
429가 올 때까지 기다릴 필요는 없습니다. API가 제한을 공개한다면, 처음부터 그에 맞춰 설계하세요.
HTTP Request integrations 를 사용하면 전용 n8n 노드가 없는 서비스까지 포함해 REST API 를 호출할 수 있습니다. API가 일정한 속도로만 요청을 받을 수 있다는 것을 알고 있다면, HTTP Request 노드로 항목을 배치로 나누고 그 사이에 지연을 넣을 수 있습니다. 이렇게 하면 API가 속도를 늦추도록 기다리는 대신, 처음부터 요청 속도를 제어할 수 있습니다.
외부 API 요청 수를 줄이세요
경우에 따라서는 나가는 요청 수를 줄이기만 해도 API 속도 제한에 걸리는 일을 피할 수 있습니다. 이를 위한 두 가지 주요 방법이 있습니다:
- 항목을 하나씩 가져오는 대신 데이터를 미리 가져오세요. 많은 API 서비스는 단일 항목이나 필터링된 항목 배열을 가져올 수 있습니다. 워크플로의 시작 부분에서 단일 HTTP 요청으로 배열을 가져온 다음, 그 배열을 순회하세요.
- 외부 API가 정적 데이터를 저장한다면, 데이터 테이블 을 사용해 로컬에 “캐시”할 수 있습니다. 예를 들어, 클라우드 기반 CRM에는 이메일 주소가 포함된 사용자 목록이 있을 수 있습니다. 이메일을 보내거나 적절한 사람에게 연락할 때마다 이 목록을 API로 요청할 필요는 없습니다. 요청 수를 줄이기 위해 이 데이터를 데이터 테이블에 저장하면 됩니다. 외부 소스가 변경되면 데이터 테이블도 업데이트하는 것을 잊지 마세요. 즉, 사용자 추가 또는 삭제를 자동화에 동기화 단계로 포함하세요.
웹훅으로 트리거되는 자신만의 워크플로를 보호하기
트래픽이 n8n으로 들어올 때는 중요한 차이가 있습니다. Webhook 노드는 워크플로를 외부 요청에 노출할 수 있지만, n8n은 API 게이트웨이가 아니며 기본 제공되는 인바운드 속도 제한 기능을 제공하지 않습니다.
과도하거나 예측하기 어려운 트래픽을 받을 수 있는 공개 웹훅이라면, n8n 앞에 전용 API 게이트웨이나 웹 애플리케이션 방화벽(WAF)을 두세요. 이 계층은 트래픽이 워크플로에 도달하기 전에 요청 제한을 적용할 수 있습니다.
Tyk를 통해 n8n 앞에 API 게이트웨이를 추가하는 방법에 대한 커뮤니티 발표 가 있습니다.
n8n 앞에 게이트웨이가 필요할 때
많은 실행을 처리하는 셀프 호스팅 n8n 배포에서는 queue mode 를 사용하면 워커가 실행을 독립적으로 처리할 수 있습니다. 동시성 제어 로 동시에 실행되는 프로덕션 실행 수를 제한할 수도 있습니다.
이러한 기능은 실행 용량을 보호하지만, API 속도 제한과는 다른 문제를 해결합니다. 이들은 서드파티 API가 요청을 제한하는 것을 막지 못하며, n8n을 인바운드 속도 제한기로 바꾸지도 않습니다. 따라서 여전히 나가는 요청의 속도를 조절하고, 들어오는 대량 트래픽에는 게이트웨이를 사용해야 합니다.
API 속도 제한에 맞서지 말고, 그에 맞게 설계하세요
API 속도 제한은 양면적인 문제입니다. API 제공자는 트래픽을 제어해야 하고, 그 API를 호출하는 워크플로는 설정된 제한을 준수해야 합니다. 두 측면을 모두 이해하면 요청량이 늘어나도 계속 실행될 수 있는 자동화를 구축하는 데 도움이 됩니다.
n8n은 서드파티 API가 요청을 제한하는 것을 막을 수는 없습니다. 하지만 워크플로에 재시도와 배치 동작을 내장하면, 429 오류는 실행 실패가 아니라 잠시 멈춤으로 바뀔 수 있습니다.
출처
- 원문: https://blog.n8n.io/api-rate-limiting/ (2026-09-18 · n8n team)