What the status code means
429 was added to HTTP in RFC 6585 in 2012. It means the client is being rate limited: the request was fine, but it arrived too soon after too many others.
It is a temporary refusal. Unlike 401 Unauthorized or 400 Bad Request, sending the same request later should work without changes.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
{ "error": "rate limited, try again in 12 seconds" }Common causes
- A burst of parallel calls: a loop or
Promise.allthat fires hundreds of requests at once. - Several processes sharing one key: each stays under the limit alone, but together they exceed it.
- Retry storms: failed calls retried instantly, which adds load exactly when the server is already refusing.
- Crawling pages too fast: paging through a long list with no pause between pages.
- A daily or monthly quota running out: some APIs also answer 429 when a longer-term allowance is used up.
How to fix it
- Read the
Retry-Afterheader. It gives either a number of seconds or a date. Wait at least that long. - If there is no header, back off exponentially: wait 1s, then 2s, then 4s, adding random jitter so many clients do not retry at the same instant.
- Stop after a fixed number of attempts and surface the error, rather than retrying forever.
- Lower your concurrency. A worker pool of a few requests usually gets more done than a burst that keeps getting refused.
- Check the rate-limit headers on successful responses and slow down before you reach zero.
async function withRetry(send, attempts = 5) {
for (let i = 0; i < attempts; i++) {
const res = await send();
if (res.status !== 429) return res;
const wait = Number(res.headers.get('retry-after')) || 2 ** i;
await new Promise(r => setTimeout(r, (wait + Math.random()) * 1000));
}
throw new Error('Still rate limited after retries');
}When it is not really a 429 problem
Some servers answer 503 Service Unavailable when they are overloaded, and some return 429 for blocked traffic that no amount of waiting will fix. If waiting the full Retry-After time never helps, the cause is usually an exhausted quota, a blocked key or a platform outage rather than your speed.
In Monocrawl
What a 429 looks like in Monocrawl
When a key or account goes over its limit, Monocrawl answers 429 with error type RATE_LIMITED, a retry-after header and the scope that was hit (key, account or free-account) in error.details.scope. A refused call is never charged.
{
"success": false,
"error": {
"type": "RATE_LIMITED",
"message": "Rate limit exceeded for this key (600 requests/minute).",
"status": 429,
"doc_url": "https://www.monocrawl.com/docs/errors#rate-limited",
"details": { "retry_after_seconds": 8, "scope": "key", "limit_per_minute": 600 }
},
"credits_used": 0,
"request_id": "req_…"
}Every error links to its fix through doc_url, so a script or an agent can branch on error.type instead of parsing messages.
Common questions
Is a 429 error my fault or the server’s?
Usually it is the client sending too fast for its limit. The request itself is valid; it just needs to wait.
How long should I wait after a 429?
As long as the Retry-After header says. Without it, start at about a second and double the wait on each retry.
Can a 429 get my key banned?
Ignoring 429s and retrying instantly can lead some APIs to block a key or IP address. Backing off as asked avoids that.
Sources