Example HTTP Response
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
{"error": "Rate limit exceeded"}- API rate limit exceeded
- Too many login attempts
- Aggressive scraping detected
What does this mean?
Whoa, slow down there! You're hitting refresh like there's a prize. Take a breather and try again later.
Technical Definition
The user has sent too many requests in a given amount of time (rate limiting).
RFC Says
"The 429 (Too Many Requests) status code indicates that the user has sent too many requests in a given amount of time ('rate limiting'). The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request."
Plain English:
429 means 'Slow down! You're making too many requests too quickly.' This is the standard rate limiting response. Include a Retry-After header to tell clients when they can try again, and ideally include headers like X-RateLimit-Limit and X-RateLimit-Remaining to help clients stay within limits.
Common Misinterpretation
Always include helpful headers with 429: Retry-After (when to retry), X-RateLimit-Limit (max requests allowed), X-RateLimit-Remaining (how many are left), and X-RateLimit-Reset (when the limit resets). Don't just return 429 with no guidance.
Ready-to-use code for returning this HTTP status in your application:
// Express.js
app.get('/example', (req, res) => {
res.status(429).json({
error: 'Too Many Requests',
message: 'Your error message here'
});
});
// Native HTTP
const http = require('http');
http.createServer((req, res) => {
res.writeHead(429, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
error: 'Too Many Requests',
message: 'Your error message here'
}));
}).listen(3000);- Client has exceeded their request quota/rate limit
- Protecting against abuse, scraping, or brute force attacks
- Include Retry-After header with seconds or date to wait
- Use 503 when the entire service is overloaded, not just one client