429 Too Many Requests

Client error: the problem lies with the request. Repeating it unchanged will normally fail again.

When a server should send it. When a client has sent too many requests in a given time. Add Retry-After with the seconds to wait (or a date), and say which limit was hit in the body or in rate-limit headers.

Common causes. Scripts or apps calling an API in a tight loop, scrapers, or many users behind one shared address.

What to do. Slow down and retry after the time in the Retry-After header, with exponential backoff in code.

Browsers and HTTP clients. Browsers show the body. Well-behaved API clients and crawlers back off, ideally honouring Retry-After and adding exponential backoff with jitter.

Google Search. Treated as a sign the server is overloaded, like a server error: Googlebot slows its crawl rate. URLs that keep returning 429 are eventually dropped from the index. Source: Google Search Central, How HTTP status codes, and network and DNS errors affect Google Search.

Caching. Not cacheable by default (RFC 9110 section 15.1 does not list it). A cache stores it only when the response says so with Cache-Control or Expires.

HTTP/1.1 429 Too Many Requests
Retry-After: 120
Content-Type: text/plain

Too Many Requests

location /example {
    add_header Retry-After '120' always;
    return 429;
}

Header always set Retry-After "120"
RewriteEngine On
RewriteRule ^example$ - [R=429,L]

header('Retry-After: 120');
http_response_code(429);
echo 'Too Many Requests';
exit;

res.writeHead(429, { 'Retry-After': '120', 'Content-Type': 'text/plain' });
res.end('Too Many Requests');

# in a view function
return 'Too Many Requests', 429, {'Retry-After': '120'}