API rate limit exceeded in n8n: fix 429s without duplicate writes
Fix API rate limit exceeded errors in n8n: read the 429, batch requests, retry after the limit window and use idempotency keys to avoid duplicate writes.
Checked against the cited sources on .
Prerequisites and goal
An "API rate limit exceeded" error means the service you're calling wants you to send fewer requests. In n8n, it can show up as an HTTP 429 response from an HTTP Request node. In this tutorial, you'll build a workflow that handles those 429s and doesn't send the same write twice when it retries.
Before you start, have these ready:
Sources: Handle rate limits | Nodes | n8n Docs, 429 Too Many Requests - HTTP | MDN
Step-by-step: handle API rate limit exceeded errors
Work through the steps in order. After each one, run the workflow again and check the result before you add the next change. That way you'll know which change made the difference.
Fix the 429s one step at a time
- Reproduce: Trigger the 429 and read the error in the node's output panel.
- Inspect: Return the status code and headers, and look for Retry-After.
- Batch: Set Items per Batch and Batch Interval to fit the API's limits.
- Retry: Turn on Retry On Fail with a wait longer than the rate-limit window.
- Protect writes: Add an idempotency key to POST requests when the API supports one.
First, reproduce the API rate limit exceeded error. According to the n8n docs, when a service returns error 429, the node fails with a message saying the service is receiving too many requests. You can read that message in the node's output panel.
Next, turn on the HTTP Request node's Include Response Headers and Status response option. The n8n docs say it returns the status code and headers along with the body. MDN says a 429 response may include a Retry-After header that tells the client how long to wait. The header is optional, though, and each server sets its own rules. The n8n docs don't explain how to act on Retry-After automatically, so for now, treat it as information you read yourself.
Then space out your requests. In the HTTP Request node's Batching option, Items per Batch sets how many items go out together, and Batch Interval sets the wait between batches in milliseconds. Choose values that fit within the limits the API documents.
After that, open the node's Settings and turn on Retry On Fail. The n8n docs say to set Wait Between Tries to longer than the rate-limit window. Those docs don't document a maximum number of tries or exponential waits.
Sources: Handle rate limits | Nodes | n8n Docs, HTTP Request | Nodes | n8n Docs, 429 Too Many Requests - HTTP | MDN
Protect retried writes with idempotency keys
Finally, protect your writes. In Stripe's API, all POST requests accept idempotency keys. Repeating a request with the same key returns the saved first result instead of running the operation again. This behavior is specific to Stripe. Here's our editorial suggestion: send the key in the way your API documents, and only when it documents support for idempotency keys. Build it from a stable business ID, such as an order number, rather than a random value that changes on every retry.
Sources: Idempotent requests | Stripe API Reference
Expected results and troubleshooting
Once batching and retries are set up, you should see fewer 429 errors. If an API rate limit exceeded error still appears, retries with a wait longer than the rate-limit window give a later attempt a chance to succeed, but a 429 can still stop the node if the limit persists. If something still goes wrong, find the symptom below.
| Symptom | Likely cause | What to check |
|---|---|---|
| 429s continue | Batches are too large or too close together | Lower Items per Batch or raise Batch Interval |
| 429s continue after retries | Wait Between Tries is shorter than the window | Set the wait longer than the rate-limit window |
| Duplicate records | Retried POST requests have no idempotency key | Check whether the API supports idempotency keys |
| Duplicates even with a key | The key changes on each retry | Build the key from a stable business ID |
If retries keep firing at the same moment, look at an older piece of general guidance. In a 2017 post on its engineering blog, Stripe recommended exponential backoff, where the wait doubles after each failure, plus random jitter so that many clients don't retry at once. That post is several years old, and none of this is a built-in n8n feature. Any n8n version of it is a pattern you design yourself.
Sources: Handle rate limits | Nodes | n8n Docs, HTTP Request | Nodes | n8n Docs, Idempotent requests | Stripe API Reference, Designing robust and predictable APIs with idempotency
