n8n 2.47.0 推出 Public API rate limits

n8n now lets admins cap how many public API requests each API key can make, so a single runaway workflow hits its API key's limit instead of blocking other teams.

Rate limiting is available from n8n 2.47.0 on every plan, on n8n Cloud and self-hosted. It works alongside idempotency keys (available since n8n 2.45.0), which make retries safe, ensuring clients calling your instance know when to slow down and when to retry.

Why rate limits matter when several teams share one instance

When several teams build on the same n8n instance, the public API becomes something many people depend on at once. API clients built by different teams call it, and so do n8n workflows that call the API of their own instance through the n8n node or the HTTP Request node.

Those workflows can create a lot of traffic in a short time. 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, and some customers have been building their own rate limiters around n8n to protect against it.

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.

What public API rate limits do in n8n

Rate limits put a ceiling on how much traffic each API key can send to your instance, so a busy or runaway client hits its own limit instead of blocking other teams, and the instance stays protected from runaway automation.

• You decide how much traffic is acceptable. Reads and writes get separate limits, both across all endpoints and per endpoint, so you can set a tighter limit on writes than on reads. Each API key has its own count within those limits.
• Clients get a clear signal when they reach a limit. n8n answers with a 429 response that includes Retry-After and rate-limit headers, so clients know when to retry and how many requests they have left, and can slow down before they reach the limit.
• You can start with sensible defaults and adjust as you go. Every limit starts with a default value, and changes you make in the settings page or through the API apply immediately, without a restart.
• The protection holds as you scale out. 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.

How to turn on rate limits in n8n

Rate limiting is off by default, so you decide when to switch it on. You can configure it in whichever of three ways fits how you run n8n:

• In the settings page: go to Settings > Policies > Public API Limits, turn on Enable API key rate limits, adjust the limits and windows, and select Enable limits.
• Through the public API: use GET /api/v1/settings/rate-limits to read the current settings and PUT /api/v1/settings/rate-limits to replace them. The API key needs the securitySettings:manage scope.
• With environment variables on self-hosted: set N8N_PUBLIC_API_RATE_LIMIT_ENABLED to true and restart n8n, then use the N8N_PUBLIC_API_RATE_LIMIT_* variables to change individual limits and windows.

Changes in the settings page or through the API apply immediately, without a restart. An environment variable overrides both, and the settings page shows that field as locked, so the value stays fixed until you change the variable and restart n8n.

How to keep your API clients and workflows within the limits

API clients can read the rate-limit headers to know when to slow down and when to retry. Four habits help them stay within the limits:

• Wait for the number of seconds in Retry-After before retrying.
• Add a small random delay of up to 5 seconds, so retries from different clients spread out.
• Watch X-RateLimit-Remaining, and slow down as it gets close to 0 until the time in X-RateLimit-Reset.
• Spread large jobs out, sending requests at a steady rate across the window.

Workflows that call the n8n API of their own instance need one extra step. The n8n node and the HTTP Request node send one request per item and fail on a 429, so add Batching to the node (in Request Options for the n8n node, and in Options for the HTTP Request node) and set Items per Batch and 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.

How idempotency keys make retries safe

Rate limits mean clients will sometimes get a 429 and need to try again, and retrying a POST carries a risk: if the first request already succeeded, the retry can create a duplicate. Idempotency keys make those retries safe, so clients can back off after a 429 and try again with confidence.

Send an Idempotency-Key header with a public API POST request. If the request succeeds, n8n stores the response for 12 hours, and a retry with the same key and body gets that stored response instead of running the POST again. If the first request fails, n8n releases the key, so the retry runs normally.

The API idempotency documentation covers the key format and the responses for conflicting or in-progress requests.

Frequently Asked Questions

What counts toward the n8n public API rate limit?

Only requests that use an API key at /api/v1 count toward the limits. Requests from the n8n editor don't count. Each API key has its own count, and every key works within the same limits.

How do I give one integration more headroom than the others?

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.

What happens if I change a rate limit while requests are in progress?

The new limit applies immediately. If the new limit is lower than an API key's current count, that key's next request gets a 429, and the count resets when the window ends.

How do I turn off one type of rate limit?

Set that limit to 0. You can turn off reads or writes, globally or per endpoint, and keep the other limits in place. When rate limiting is enabled, at least one limit must be more than 0.

Why does my n8n workflow fail with a 429 error when it calls the n8n API?

The workflow is sending more requests than the instance's rate limits allow. The n8n node and the HTTP Request node run once for each item and fail on a 429, so a large list of items can reach a limit quickly. Add Batching to the node and set Items per Batch and Batch Interval to keep the request rate under the limits.

What to do next

Update to n8n 2.47.0 or later, turn on rate limits in Settings > Policies > Public API Limits, and check the API rate limits documentation for the full configuration reference. If your clients send POST requests, add idempotency keys at the same time using the API idempotency documentation.