n8n API Rate Limit Handling

Why API rate limits break real n8n workflows

Rate limits show up at the least convenient moment: the launch email goes out, a backlog of forms arrives, a vendor slows down, or a nightly sync processes three times the normal volume. The workflow worked perfectly in testing because testing did not look like production. Production has bursts, retries, partial failures, and several workflows sharing the same vendor account.

The naive fix is to add retries. That helps only when the retry is paced and safe. A workflow that retries every failed request immediately can exceed the quota again, create duplicate downstream actions, and hide the real failure until a customer notices. The workflow appears busy while the business outcome is stuck.

n8n gives you the building blocks: queues, wait nodes, error workflows, item batches, execution data, and custom HTTP handling. The production work is deciding where pacing belongs, how to read vendor signals, when to retry, when to stop, and how to replay failed items without creating duplicates.

The four rate limits you need to design for

Not every limit is a simple requests-per-minute number. Some vendors enforce a burst limit, a daily quota, a concurrency cap, or a cost budget tied to account tier. AI providers may limit requests, tokens, or both. CRMs often limit per app and per user. Email APIs can apply different rules for sending, reading, and search endpoints.

A reliable workflow treats the vendor limit as an external dependency with its own behavior. It reads response headers where available, stores enough state to avoid stampedes, and does not assume that every 429 means the same thing. A one-second wait might fix a burst limit, but it does nothing for a daily quota that resets tomorrow.

The practical move is to document the limit next to the credential. If the workflow uses the same CRM account as five other automations, the rate budget is shared. If the workflow calls an AI model with long prompts, token limits may be the bottleneck even when request count looks low.

Rate-limit handling patterns that actually work

Pick the pattern by failure mode, not by habit. The right answer for a search endpoint may be wrong for a payment endpoint, and the right answer for one vendor may be unsafe for another.

Copy-paste response routing logic

This is not vendor-specific code. It is the shape of the decision you want every rate-limited workflow to make: retry later only when later can help, preserve idempotency, and route permanent failures somewhere visible. n8n’s built-in Retry On Fail node setting (with maxTries and waitBetweenTries) handles transient errors, but it uses a fixed wait and ignores Retry-After, so quota pacing still needs explicit logic like the routing below.

If you need the node-level setup first, use the n8n HTTP Request node guide for authentication, headers, pagination, and response handling before adding rate-limit routing.

// HTTP Request node response handling concept for n8n
// Store attempt_count and idempotency_key with each item before calling the API.

if (statusCode === 429) {
  // Retry-After can be delta-seconds OR an HTTP date - handle both.
  const retryAfter = headers["retry-after"];
  const hintSeconds = retryAfter
    ? (isNaN(Number(retryAfter))
        ? Math.max(0, (Date.parse(retryAfter) - Date.now()) / 1000)
        : Number(retryAfter))
    : null;
  const waitSeconds = hintSeconds != null
    ? hintSeconds
    : Math.min(900, Math.pow(2, attempt_count) * 30 + random_jitter_seconds);

  return {
    route: "retry_later",
    wait_seconds: waitSeconds,
    reason: "rate_limited",
    idempotency_key,
    attempt_count: attempt_count + 1
  };
}

if (statusCode >= 500 && attempt_count < 5) {
  return { route: "retry_later", reason: "temporary_vendor_failure", idempotency_key };
}

if (statusCode >= 400) {
  return { route: "dead_letter", reason: "non_retryable_response", statusCode, response_body, idempotency_key };
}

return { route: "success", vendor_id: response.id, idempotency_key };

Idempotency is what makes retries safe

A retry is only safe if the repeated request cannot create a second business action. For read calls, this is usually simple. For writes, sends, creates, payments, tickets, invoices, and model jobs, it is the main design question. If the API supports idempotency keys, use them. If it does not, store your own external request key and check before creating another object.

In n8n, that means each item should carry a stable key derived from business identity, not from the execution attempt. A customer ID plus invoice month is stable. A random value generated on every retry is not. When the workflow wakes up after a wait, it should know whether it is continuing the same business action or starting a new one.

Idempotency also belongs in your manual replay path. If a dead-letter item is fixed and replayed tomorrow, it should not blindly repeat the external side effect if the first attempt actually succeeded but the acknowledgement failed. The review screen needs vendor response data, not just a red error badge.

A six-step n8n rate-limit runbook

This runbook keeps the workflow understandable. It prevents the two common extremes: no retry at all, or retry forever until the logs become meaningless.

1. List every vendor quota. Record request limits, token limits, daily quotas, concurrency caps, reset windows, and whether the vendor returns Retry-After or rate-limit headers.
2. Put a throttle before the API call. Use batching, queue mode, wait nodes, or a durable token bucket so the workflow does not create its own 429 storm.
3. Carry attempt state on the item. Store attempt count, last status, last wait, and idempotency key so a retry knows its history.
4. Separate retryable from permanent errors. Treat 429 and many 5xx responses differently from validation errors, authorization failures, and malformed payloads.
5. Stop after a bounded number of attempts. Send stuck work to a dead-letter path with enough context for a safe replay.
6. Measure queue age, not just errors. A workflow can have zero final errors and still be failing the business if customer work waits for hours behind a quota.

Worked example: CRM enrichment after a campaign

A campaign sends 4,000 leads into n8n in one hour. Each lead needs a CRM lookup, a company enrichment call, and a score update. In testing, ten leads completed instantly. In production, the enrichment vendor allows 120 requests per minute with a burst cap, the CRM allows fewer write calls than read calls, and both vendors share credentials with other workflows.

The safe design starts by splitting the workflow into stages. Stage one accepts the lead and writes a durable queue item. Stage two processes enrichment at a controlled rate, using a stable idempotency key based on lead ID and campaign ID. Stage three writes the score back to the CRM at a lower write pace. If enrichment returns 429, the item waits based on vendor guidance. If CRM validation fails, the item goes to review because waiting will not fix a bad field.

The business outcome is better than a faster-looking workflow. Leads still move through the system, the vendor account is not hammered, duplicate CRM updates are avoided, and operations can see queue age. If the backlog grows too large, the team can decide to buy a higher tier, reduce enrichment scope, or process lower-priority leads later.

What to monitor after launch

The most useful metrics are operational, not decorative. Track 429 count by vendor, retry attempts per item, average wait time, oldest item age, final dead-letter count, and duplicate-prevention hits. A lightweight monitoring setup can surface these without heavy tooling. If a rate limit is hurting the business, queue age will show it before a customer complaint does.

Also watch spend and quota dashboards at the vendor. An AI provider might show token spikes before n8n shows failures. A CRM might show app-level throttling even when a single workflow looks healthy. The workflow is only one view of the system.

Finally, connect the alert to an action. 429 count high is less useful than enrichment queue oldest item is 42 minutes, pause low-priority campaign branch or increase vendor quota. Monitoring should tell the operator what to do, not merely prove that the graph changed.

Common mistakes that make rate limits worse

Concurrency is not the same as throughput

Many n8n teams discover rate limits after they move to queue mode or add more workers. The internal system becomes faster, but the external vendor has not changed. Ten workers can drain your internal queue quickly while all ten hit the same API quota at once. From the vendor perspective, you did not scale responsibly; you created a concentrated spike.

The fix is to separate internal concurrency from external concurrency. Let n8n workers process independent tasks, but put a vendor-specific throttle in front of the limited endpoint. For one API, that throttle may be a Wait node and small batches. For another, it may be a Redis token bucket or a database row that tracks the next allowed call time. The exact mechanism matters less than the boundary: worker count is not allowed to decide vendor call rate by accident.

This boundary also helps with shared credentials. If three workflows use the same CRM app, they need one shared understanding of the quota. Otherwise each workflow may behave politely in isolation while the combined account exceeds the limit. A central queue or shared rate state gives operations one place to see pressure before users see delayed work.

Batching, partial failure, and replay

Batching is attractive because it reduces request count, but it changes the failure shape. If an API accepts one hundred records at a time and one record is invalid, the vendor may reject the whole batch, accept the valid records and return item-level errors, or accept everything and process failures later. Each behavior requires a different replay strategy inside n8n.

Before batching production work, test the ugly cases: one malformed item, one unauthorized item, one duplicate item, one request that times out after the vendor may have accepted it. The workflow should know whether to retry the entire batch, split the batch, replay only failed items, or send the result to a review queue. Without that design, batching can turn one bad customer record into a blocked backlog.

A good batch design keeps the original item identity through every step. Store the source ID, idempotency key, vendor response, and batch ID together. When an operator looks at a dead-letter item, they should see whether the item was never sent, sent and rejected, or sent and accepted without a clean acknowledgement. That difference decides whether replay is safe.

The simplest acceptance test is a replay drill. Take one successful item, one rate-limited item, one permanent failure, and one ambiguous timeout, then prove the workflow can explain and replay each case without creating duplicates. If the drill is confusing, production will be worse.

What other experts say

Ship a rate-safe n8n workflow

• Document every quota at the credential. Record per-minute, daily, token, and concurrency limits next to the credential, and note which other workflows share that vendor account.
• Throttle before the call. Put a Wait node, small batches, or a durable token bucket in front of the limited endpoint so the workflow never generates its own 429 storm.
• Read vendor signals on rejection. Parse Retry-After and any RateLimit headers, and handle both delta-seconds and HTTP-date formats instead of guessing a fixed wait.
• Attach attempt state to each item. Carry attempt count, last status, last wait, and a stable idempotency key derived from business identity, never from the retry attempt.
• Split retryable from permanent. Route 429 and most 5xx responses to a paced retry, but send validation, auth, and malformed-payload errors straight to review.
• Bound the retries and dead-letter the rest. Stop after a fixed attempt count and push stuck items to a queue with the vendor response attached for safe replay.
• Alarm on queue age, not just errors. Track oldest-item age per vendor so a quiet backlog behind a quota surfaces before a customer complains.
• Run a replay drill before launch. Prove the workflow can explain and re-run a success, a rate-limited item, a permanent failure, and an ambiguous timeout without creating duplicates.

Rate-limit handling readiness card