API 속도 제한
n8n v2.47요약
n8n은 API 키별로 퍼블릭 API 요청 수를 제한할 수 있습니다. n8n API의 속도 제한은 다음에서 사용할 수 있습니다. n8n API의 속도 제한은 n8n 2.47.0부터 사용할 수 있습니다. n8n은 API 키별로 요청을 집계합니다.
n8n은 API 키별로 퍼블릭 API 요청 수를 제한할 수 있습니다. 제한을 초과한 요청은 429 Too Many Requests 응답을 받습니다. 속도 제한 헤더를 읽어 제한에 도달하기 전에 요청 속도를 늦추고, 재시도하기 전에 Retry-After에 표시된 시간만큼 기다리세요.
기능 제공 여부
n8n API의 속도 제한은 다음에서 사용할 수 있습니다.
- n8n Cloud: 모든 플랜
- 셀프 호스팅: 모든 에디션
n8n API의 속도 제한은 n8n 2.47.0부터 사용할 수 있습니다. 기본적으로 꺼져 있으며 인스턴스 소유자 또는 관리자가 켭니다.
n8n이 요청을 집계하는 방법#
n8n은 API 키별로 요청을 집계합니다. 같은 사용자의 API 키 두 개는 집계가 별도로 이루어집니다.
n8n은 /api/v1에서 API 키를 사용하는 요청만 집계합니다. n8n 에디터에서 보낸 요청은 집계되지 않습니다.
n8n은 각 요청을 두 가지 유형 중 하나로 분류합니다.
| 유형 | 메서드 |
|---|---|
| 읽기 | GET |
| 쓰기 | POST, PUT, PATCH, DELETE |
읽기와 쓰기는 제한이 별도입니다. 쓰기는 읽기 제한에 포함되지 않습니다.
두 가지 제한#
각 요청은 동시에 두 가지 제한에 집계됩니다.
- 모든 엔드포인트: 모든 엔드포인트에 걸친 API 키 단위의 집계 하나입니다.
- 각 엔드포인트: 각 엔드포인트별 API 키 단위의 별도 집계입니다. 엔드포인트는 메서드와 경로의 조합입니다. 예를 들어
GET /api/v1/workflows/{workflowId}는 모든 워크플로 ID에 대해 하나의 엔드포인트입니다.
n8n은 요청을 받아들이면 두 제한 중 하나를 초과하게 될 때 해당 요청을 거부합니다. 각 제한에는 초 단위의 윈도우가 있습니다. 윈도우가 끝나면 집계가 다시 시작됩니다.
| 제한 | 기본값 | 윈도우 |
|---|---|---|
| 읽기, 모든 엔드포인트 | 1,200 | 60초 |
| 쓰기, 모든 엔드포인트 | 600 | 60초 |
| 읽기, 각 엔드포인트 | 1,000 | 60초 |
| 쓰기, 각 엔드포인트 | 500 | 60초 |
제한을 켜거나 값을 변경하려면 속도 제한 켜기를 참조하세요.
속도 제한 헤더#
성공 응답에는 다음 헤더가 포함됩니다.
| 헤더 | 의미 |
|---|---|
X-RateLimit-Limit |
한 윈도우에서 제한이 허용하는 요청 수입니다. |
X-RateLimit-Remaining |
현재 윈도우에서 남은 요청 수입니다. |
X-RateLimit-Reset |
윈도우가 끝나는 시간이며 초 단위 Unix 타임스탬프입니다. |
각 요청은 두 가지 제한에 집계됩니다. 헤더에는 남은 요청 수가 가장 적은 제한이 표시됩니다.
속도 제한이 꺼져 있거나 요청이 API 키를 사용하지 않는 경우에는 헤더가 없습니다.
제한에 도달했을 때#
제한을 초과한 요청은 다음과 같은 응답을 받습니다.
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793122230
{
"message": "Too many requests"
}
Retry-After는 기다려야 하는 시간(초)입니다. 요청이 두 제한을 모두 초과한 경우 Retry-After는 더 늦게 풀리는 쪽을 기준으로 합니다.
거부된 요청은 어떤 제한에도 집계되지 않습니다. n8n은 해당 요청을 실행하지 않습니다.
429 응답 처리#
제한 내에서 요청을 유지하고 제한에 도달했을 때 복구하려면 다음과 같이 합니다.
Retry-After만큼 기다립니다. 해당 시간(초)이 지나기 전에는 요청을 다시 보내지 마세요. 너무 일찍 재시도하면429를 다시 받습니다.- 짧은 무작위 지연을 추가합니다. 여러 클라이언트가 같은 시간만큼 기다리면 모두 동시에 재시도합니다. 각 재시도에 최대 5초의 무작위 지연을 추가하세요.
X-RateLimit-Remaining을 확인합니다. 값이 0에 가까워지면X-RateLimit-Reset에 표시된 시간까지 요청 속도를 늦추세요.- 대량 작업을 분산합니다. 많은 요청을 같은 순간에 보내지 마세요. 윈도우 동안 일정한 속도로 나누어 보내세요.
n8n 워크플로에서의 호출#
n8n 워크플로는 n8n 노드나 HTTP Request 노드 등을 사용해 자신의 인스턴스에 있는 n8n API를 호출할 수 있습니다. 노드는 항목마다 한 번씩 실행되므로 항목이 1,000개인 목록은 약 1,000개의 요청을 한꺼번에 보냅니다. 이러한 노드는 Retry-After를 기다리지 않으며 429를 받으면 노드가 실패합니다.
제한 내에서 요청을 유지하려면 노드에 Batching을 추가하세요. n8n 노드에서는 Request Options에 있고, HTTP Request 노드에서는 Options에 있습니다. 그런 다음 Items per Batch와 **Batch Interval (ms)**를 설정합니다. 예를 들어 1초마다 항목 5개를 보내면 분당 300개의 요청이 되며, 이는 모든 기본 제한보다 낮습니다.
Retry On Fail은 429를 해결하지 못합니다. 시도 사이에 최대 5초만 기다리므로 같은 윈도우 안에서 재시도되는 경우가 많고, 모든 항목에 대해 노드를 다시 실행합니다.
첫 번째 요청이 이미 성공했다면 재시도한 POST가 중복을 만들 수 있습니다. Idempotency-Key 헤더를 보내면 재시도를 안전하게 할 수 있습니다. API 멱등성을 참조하세요.
속도 제한 켜기#
인스턴스 소유자 또는 관리자는 세 가지 방법으로 제한을 켜고 변경할 수 있습니다.
- n8n 설정에서
- n8n 퍼블릭 API로
- 셀프 호스팅 인스턴스의 경우 환경 변수로
설정이나 API로 변경한 내용은 즉시 적용됩니다. n8n을 재시작할 필요가 없습니다.
설정이나 API로 속도 제한을 켜거나 끄거나, 제한 또는 윈도우를 변경하면 n8n은 이를 구독하는 각 로그 스트리밍 대상에 감사 이벤트를 보냅니다. 퍼블릭 API 속도 제한 이벤트를 참조하세요.
n8n 설정에서#
- Settings > Policies로 이동합니다.
- Public API Limits에서 Enable API key rate limits를 켭니다.
- All endpoints와 Individual endpoints의 제한과 윈도우를 설정합니다. 각 필드에는 기본값이 입력되어 있습니다.
- Enable limits를 선택합니다.
나중에 값을 변경하려면 Enable API key rate limits 옆의 편집 아이콘을 선택하고 필드를 변경한 다음 Save changes를 선택합니다. 대화 상자에서는 다음과 같이 할 수 있습니다.
- 제한 필드를 비우면 해당 제한이 제거됩니다. 필드에는 No limit이 표시됩니다.
- 행 옆의 Reset to default를 선택하면 해당 행이 기본값으로 돌아갑니다. Reset all을 선택하면 모든 행이 초기화됩니다.
속도 제한을 켜려면 하나 이상의 제한에 값이 있어야 합니다.
속도 제한을 끄려면 Enable API key rate limits를 끕니다.
n8n 퍼블릭 API로#
다음 엔드포인트를 사용합니다. API 키에 securitySettings:manage 스코프가 필요합니다.
| 엔드포인트 | 기능 |
|---|---|
GET /api/v1/settings/rate-limits |
현재 설정을 반환합니다. |
PUT /api/v1/settings/rate-limits |
설정을 교체합니다. 모든 필드를 보내야 합니다. |
예를 들어 기본값으로 제한을 켜려면 다음과 같이 합니다.
curl -X PUT 'https://<your-instance>/api/v1/settings/rate-limits' \
-H "X-N8N-API-KEY: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"globalReadLimit": 1200,
"globalReadWindowSeconds": 60,
"globalWriteLimit": 600,
"globalWriteWindowSeconds": 60,
"endpointReadLimit": 1000,
"endpointReadWindowSeconds": 60,
"endpointWriteLimit": 500,
"endpointWriteWindowSeconds": 60
}'
제한을 0으로 설정하면 제한이 없습니다. enabled가 true이면 하나 이상의 제한이 0보다 커야 합니다. GET 응답을 그대로 PUT 본문으로 보낼 수 있습니다.
이러한 요청도 API 키를 사용하므로 제한에 집계됩니다. 전체 스키마는 엔드포인트 레퍼런스를 참조하세요.
환경 변수로#
셀프 호스팅 인스턴스에서는 환경 변수로 값을 설정할 수 있습니다. N8N_PUBLIC_API_RATE_LIMIT_ENABLED를 true로 설정하고 n8n을 재시작하세요.
제한이나 윈도우를 변경하려면 해당 환경 변수를 설정합니다.
| 제한 | 제한 변수 | 윈도우 변수 |
|---|---|---|
| 읽기, 모든 엔드포인트 | N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_LIMIT |
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_WINDOW_SECONDS |
| 쓰기, 모든 엔드포인트 | N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_LIMIT |
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_WINDOW_SECONDS |
| 읽기, 각 엔드포인트 | N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_READ_LIMIT |
N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_READ_WINDOW_SECONDS |
| 쓰기, 각 엔드포인트 | N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_WRITE_LIMIT |
N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_WRITE_WINDOW_SECONDS |
제한을 0으로 설정하면 해당 제한이 꺼집니다. 윈도우는 1초 이상이어야 합니다.
예를 들어 모든 엔드포인트에 걸쳐 분당 쓰기를 300회로 허용하려면 다음과 같이 합니다.
N8N_PUBLIC_API_RATE_LIMIT_ENABLED=true
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_LIMIT=300
환경 변수는 설정의 값보다 우선합니다. 해당 필드는 설정 페이지나 API로 변경할 수 없습니다.
- 설정 페이지에는 해당 필드가 잠긴 상태로 표시됩니다.
GET응답의envManagedFields에 해당 필드가 나열됩니다.- 해당 필드를 변경하는
PUT은409 Conflict응답을 받습니다. 현재 값을 그대로 보내는PUT은 성공합니다.
잠긴 필드를 변경하려면 환경 변수를 변경하고 n8n을 재시작하세요.
전체 목록은 배포 환경 변수를 참조하세요.
멀티 메인 설정#
멀티 메인 설정에서는 모든 메인 인스턴스가 Redis를 통해 API 키별 집계를 하나로 공유합니다. 한 메인에서 제한에 도달한 API 키는 윈도우가 끝날 때까지 모든 메인에서 429를 받습니다. 설정이나 API로 변경한 내용은 모든 메인에 적용됩니다.