n8n 中文文档

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 响应

要保持在限制范围内,并在达到限制时恢复:

  1. 等待 Retry-After。 在经过该秒数之前不要再次发送请求。过早重试会再次收到 429。
  2. 添加少量随机延迟。 如果多个客户端等待相同的时间,它们会同时重试。请为每次重试添加最多 5 秒的随机延迟。
  3. 关注 X-RateLimit-Remaining。 当它接近 0 时,放慢速度,直到 X-RateLimit-Reset 中的时间。
  4. 分散大型任务。 不要在同一时刻发送大量请求,而应在整个时间窗口内以稳定的速率发送。

来自 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 设置中

  1. 转到 Settings > Policies。
  2. 在 Public API Limits 下,开启 Enable API key rate limits。
  3. 为 All endpoints 和 Individual endpoints 设置限制和时间窗口。每个字段的初始值都是默认值。
  4. 选择 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 进行的更改会应用到每个主实例。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。