429 Too Many Requests
Description
The 429 Too Many Requests status code indicates that the user has sent too many requests in a given amount of time ("rate limiting"). This status code is used to enforce usage limits on API services, prevent abuse, and ensure fair resource allocation among clients.
This status code is commonly used when: - A client exceeds the allowed number of requests per time period - A server needs to protect itself from excessive load - An API implements tiered access with different rate limits - A service needs to prevent scraping or automated abuse
The 429 Too Many Requests response typically includes headers that provide information about the rate limit, such as how many requests are allowed, how many remain, and when the limit will reset.
Syntax
The server responds with a 429 Too Many Requests status and typically includes rate limit information:
HTTP/1.1 429 Too Many Requests
Retry-After: [seconds until the limit resets]
X-RateLimit-Limit: [requests allowed per time window]
X-RateLimit-Remaining: [requests remaining in current window]
X-RateLimit-Reset: [unix timestamp when the window resets]
Content-Type: application/json
Content-Length: [length in bytes]
{
"error": "Too Many Requests",
"message": "Rate limit exceeded"
}
Examples
Basic Rate Limiting Example
A client exceeds the allowed number of requests per minute:
Client Request:
GET /api/data HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Server Response:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623761445
Content-Type: application/json
Content-Length: 187
{
"error": "Too Many Requests",
"message": "You have exceeded the rate limit of 60 requests per minute",
"retry_after": 30,
"documentation_url": "https://api.example.com/docs/rate-limits"
}
Tiered API Access Example
A client on a free tier exceeds their lower rate limit:
Client Request:
GET /api/search?q=example HTTP/1.1
Host: search.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Server Response:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623764400
Content-Type: application/json
Content-Length: 243
{
"error": "Too Many Requests",
"message": "Rate limit exceeded for free tier",
"current_plan": "free",
"current_limit": "100 requests per hour",
"upgrade_url": "https://search.example.com/pricing",
"reset_time": "2023-06-15T15:00:00Z"
}
IP-Based Rate Limiting Example
A client from a specific IP address makes too many requests:
Client Request:
Server Response:
HTTP/1.1 429 Too Many Requests
Retry-After: 900
Content-Type: text/html
Content-Length: 345
<!DOCTYPE html>
<html>
<head>
<title>Too Many Requests</title>
</head>
<body>
<h1>429 Too Many Requests</h1>
<p>Your IP address has made too many login attempts.</p>
<p>For security reasons, please wait 15 minutes before trying again.</p>
<p>If you believe this is an error, please contact support.</p>
</body>
</html>
Summary
The 429 Too Many Requests status code is a critical component of API management and web service protection. It allows servers to enforce usage limits, prevent abuse, and maintain service quality for all users. By including information about the rate limit and when it will reset, servers help clients implement appropriate backoff strategies and adjust their request patterns. This status code is particularly important for public APIs, shared services, and any system that needs to allocate resources fairly among multiple clients.