Blog

n8n Public API: Configure Rate Limiting to Avoid 429 Errors and Keep Teams Productive

By ·16 Nov 2026 ·6 min ·Theme: No-code
Contents
    n8n Public API: Configure Rate Limiting to Avoid 429 Errors and Keep Teams Productive

    Are your n8n workflows failing with 429 Too Many Requests errors? Enable and configure the Public API’s rate limiting to distribute requests without disrupting teams. This guide covers default limits, how to interpret response headers, and using idempotency keys for safe retries — including a ready-to-use n8n template.

    Why n8n’s Public API Rate Limiting is Essential

    The n8n Public API enables critical automation tasks: triggering workflows, retrieving executions, or syncing data between tools. Without control, a spike in requests can overwhelm your instance, blocking all teams with 429 Too Many Requests errors. These interruptions disrupt workflows and force ops teams to manually restart processes — wasting time and productivity.

    n8n’s built-in rate limiting (available since 2024) solves this by:

    • Capping requests per API key without affecting other users on the instance.
    • Providing response headers to dynamically adjust request rates.
    • Enabling safe retries with idempotency keys to prevent duplicates.

    This guide explains how to enable, configure, and leverage these mechanisms for stable workflows.

    1. Enable and Configure Rate Limits

    Default Limits and Request Counting

    n8n applies two simultaneous levels of limits for each API key (source: F1, F2):

    • Global limit: Total requests allowed across all endpoints.
    • Per-endpoint limit: Requests allowed for a specific endpoint (e.g., GET /api/v1/workflows/{workflowId}).

    Requests are categorized into two types, with separate limits:

    Request Type Global Limit (60s) Per-Endpoint Limit (60s)
    Read (GET) 1,200 1,000
    Write (POST, PUT, PATCH, DELETE) 600 500

    A request is rejected if it exceeds either of the two limits. For example, 1,001 GET requests to the same endpoint trigger a 429 error, even if the global limit (1,200) isn’t reached.

    Diagram of n8n rate limits: two levels of limits (global and per-endpoint) for read and write requests.
    The two levels of limits in n8n: global (all endpoints) and per-endpoint. A request is rejected if it exceeds either limit.

    Methods to Enable Rate Limiting

    You can enable or modify limits via three methods (source: F6):

    a. Via n8n Settings (UI)
    1. Go to Settings > Policies.
    2. Enable Enable API key rate limits.
    3. Configure limits and windows (in seconds) for All endpoints and Individual endpoints.
    4. Click Enable limits.

    Changes apply immediately, without restarting n8n.

    b. Via the Public API

    Use the PUT /api/v1/settings/rate-limits endpoint to modify limits. Example payload:

    {
      "globalReadLimit": 1200,
      "globalReadWindowSeconds": 60,
      "globalWriteLimit": 600,
      "globalWriteWindowSeconds": 60,
      "endpointReadLimit": 1000,
      "endpointReadWindowSeconds": 60,
      "endpointWriteLimit": 500,
      "endpointWriteWindowSeconds": 60
    }

    Requests to this endpoint also count toward rate limits (source: F6).

    c. Via Environment Variables (Self-Hosted)

    On a self-hosted instance, set the following variables before starting n8n (source: F7):

    N8N_PUBLIC_API_RATE_LIMIT_ENABLED=true
    N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_LIMIT=1200
    N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_WINDOW_SECONDS=60
    N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_LIMIT=600
    N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_WINDOW_SECONDS=60
    N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_READ_LIMIT=1000
    N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_READ_WINDOW_SECONDS=60
    N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_WRITE_LIMIT=500
    N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_WRITE_WINDOW_SECONDS=60

    Warning: Environment variables override n8n settings. To modify a limit managed by an environment variable, you must restart n8n (source: F7).

    2. Interpret Rate-Limiting Headers to Avoid 429 Errors

    When a request succeeds, n8n includes headers to help you stay under limits (source: F3):

    • X-RateLimit-Limit: Maximum allowed requests in the window.
    • X-RateLimit-Remaining: Remaining requests in the current window.
    • X-RateLimit-Reset: Unix timestamp (in seconds) for the end of the window.

    These headers reflect the most restrictive limit (global or per-endpoint) for the current request. They are absent if rate limiting is disabled or if the request doesn’t use an API key.

    Diagram of n8n rate-limiting headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After.
    n8n rate-limiting headers: how to use them to adjust request rates and avoid 429 errors.

    What to Do When You Get a 429

    A 429 Too Many Requests response includes a Retry-After header indicating how many seconds to wait before retrying (source: F4). Example response:

    HTTP/1.1 429 Too Many Requests
    Retry-After: 15
    Content-Type: application/json
    
    {
      "code": 429,
      "message": "Too Many Requests"
    }

    To handle a 429 error:

    1. Wait for the duration specified in Retry-After before retrying. A premature retry triggers another 429.
    2. Add a random delay (up to 5 seconds) to avoid multiple clients retrying simultaneously (source: F5).
    3. Monitor X-RateLimit-Remaining: If the value is close to 0, slow down until the window resets (X-RateLimit-Reset).
    4. Spread out requests over the entire window to avoid spikes.

    3. Use Idempotency Keys for Safe Retries

    Idempotency keys ensure that a retried POST request doesn’t create duplicates. They’re critical for endpoints like workflow creation or execution retries (source: F10).

    How It Works

    • Add an Idempotency-Key header to your POST request. Example: Idempotency-Key: req_abc123.
    • The key must be unique per request (e.g., a UUID v4) and contain 1–128 visible ASCII characters (no spaces).
    • n8n stores the first successful response for this key for 12 hours (source: F11).
    • A retry with the same key returns the initial response without re-running the request.

    Example Usage

    Request to create a workflow with an idempotency key:

    curl -X POST 'https://your-instance.n8n.cloud/api/v1/workflows' \
      -H 'accept: application/json' \
      -H 'X-N8N-API-KEY: your_api_key' \
      -H 'Idempotency-Key: workflow_creation_123e4567' \
      -H 'Content-Type: application/json' \
      -d '{"name": "My Workflow", "nodes": [...]}'

    If the request fails (e.g., timeout), retry it with the same key: n8n will return the initial response if the first request succeeded, preventing duplicates.

    Limitations

    • Idempotency keys only apply to POST requests (ignored for GET, PUT, PATCH, DELETE) (source: F12).
    • The same key with a different path, query string, or body returns a 422 error (source: F12).
    • After 12 hours, the same key will re-run the request (risk of duplicates).

    4. Best Practices for n8n Workflows Calling the Public API

    Configure Batching to Stay Under Limits

    In an n8n workflow, nodes like HTTP Request or n8n run once per item. Without control, a list of 1,000 items sends 1,000 simultaneous requests — far exceeding the limits (source: F8).

    To avoid this, enable batching in the node options:

    • Items per Batch: Number of items processed per batch (e.g., 5).
    • Batch Interval (ms): Delay between batches (e.g., 1,000 ms for 1 second).

    Example: 5 items/second = 300 requests/minute, well under the default limits (1,000 reads/60s or 500 writes/60s).

    Diagram of batching in an n8n workflow: configuring Items per Batch and Batch Interval to control request rates.
    Batching in n8n: how to distribute requests to avoid exceeding rate limits.

    Why Retry On Fail Doesn’t Resolve 429 Errors

    The Retry On Fail option in n8n nodes waits up to 5 seconds between attempts — often within the same rate-limiting window. Additionally, it re-runs the node for each item, which can create duplicates for POST requests (source: F9).

    Alternative solution: Use a Wait node to respect Retry-After, or a Loop Over Items node with a custom delay.

    Ready-to-Use n8n Template

    Here’s a template for an n8n workflow that:

    • Fetches data via the Public API with batching.
    • Handles 429 errors by respecting Retry-After.
    • Uses idempotency keys for POST requests.

    Download the template here (link to official documentation).

    5. Key Limitations and Constraints

    • Environment variables: Changes may require restarting n8n for some limits (e.g., disabling a limit managed by env) (source: F7).
    • Missing headers: If rate limiting is disabled or the request doesn’t use an API key, X-RateLimit-* headers are absent (source: F3).
    • Idempotency keys: Limited to POST endpoints and valid for 12 hours only (source: F11, F12).
    • No rate limiting for external APIs: This guide covers only n8n’s Public API. For third-party APIs called from n8n, use mechanisms like queues or custom delays.

    Conclusion: Stability and Productivity

    Configuring n8n’s Public API rate limiting prevents 429 errors and keeps workflows running smoothly. Here are the key steps:

    1. Enable limits via settings, the API, or environment variables.
    2. Monitor X-RateLimit-Remaining and Retry-After headers to adjust request rates.
    3. Use idempotency keys for critical POST requests.
    4. Configure batching in your n8n workflows to stay under limits.

    For further reading, explore our guides on:

    Article prepared with AI assistance and checked against the sources consulted.

    n8n rate limiting API automation ops idempotency keys 429 errors
    Read next
    A similar project to scope? Let's talk. Get in touch with Keerok →
    © 2026 Keerok · All rights reserved Cran · Keerok's media