API 速率限制
n8n 可以限制每个 API 密钥发出的公共 API 请求数量。超出限制的请求会收到 429 Too Many Requests 响应。请读取速率限制标头,在达到限制之前放慢速度,并在重试前等待 Retry-After 中给出的时间。
提示
Feature availability 功能可用性
n8n API 的速率限制可用于:
- n8n Cloud: 所有计划
- Self-hosted: 所有版本
n8n API 的速率限制从 n8n 2.47.0 起可用,默认关闭,由实例 Owner 或 Admin 开启。
n8n 如何计算请求
n8n 按 API 密钥分别计数。同一用户的两个 API 密钥分别计数。
n8n 只统计在 /api/v1 上使用 API 密钥的请求。来自 n8n 编辑器的请求不计入。
n8n 将每个请求归入以下两种类型之一:
| 类型 | 方法 |
|---|---|
| 读取 | GET |
| 写入 | POST、PUT、PATCH、DELETE |
读取和写入有各自独立的限制。写入不计入读取限制。
两种限制
每个请求会同时计入两种限制:
- 所有端点: 该 API 密钥在所有端点上的总计数。
- 每个端点: 该 API 密钥在每个端点上的单独计数。端点由方法和路径组成。例如,对于所有工作流 ID,
GET /api/v1/workflows/{workflowId}都是同一个端点。
如果接受某个请求会超出任一限制,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 API,例如使用 n8n 节点或 HTTP Request 节点。节点会为每个数据项运行一次,因此一个包含 1,000 个数据项的列表会一次性发送约 1,000 个请求。这些节点不会等待 Retry-After,并且会在收到 429 时失败。
要保持在限制范围内,请为节点添加 Batching。在 n8n 节点中,它位于 Request Options 中;在 HTTP Request 节点中,它位于 Options 中。然后设置 Items per Batch 和 Batch Interval (ms)。例如,每秒处理 5 个数据项,每分钟会发送 300 个请求,低于所有默认限制。
Retry On Fail 无法解决 429。它在两次尝试之间最多等待 5 秒,这通常仍在同一个时间窗口内,而且它会为每个数据项重新运行节点。
如果第一个请求实际上已经成功,重试的 POST 可能会创建重复项。请发送 Idempotency-Key 标头,使重试变得安全。请参阅 API 幂等性。
开启速率限制
实例 Owner 或 Admin 可以通过三种方式开启和更改限制:
- 在 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 scope。
| 端点 | 作用 |
|---|---|
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 密钥,因此它们也会计入限制。完整的 schema 请参阅端点参考。
使用环境变量
在自托管实例上,你可以使用环境变量设置这些值。将 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 进行的更改会应用到每个主实例。