# 429 Too Many Requests

> https://http-status.org/docs/429

**Family:** 4xx Client Error

## Rationale

Client sent too many requests in a given amount of time (rate limiting).

## In Plain Terms

Slow down! You're making too many requests too quickly. Wait a bit and try again later.

## Description

The HTTP 429 Too Many Requests status code indicates the user has sent too many requests in a given amount of time (rate limiting).

## Server Perspective

### Usage
- Return 429 for per-user, per-token, per-IP, or per-tenant limits
- Use it for abusive bursts or quota exhaustion when the service is otherwise healthy
- API rate limiting exceeded
- Too many login attempts
- Request quota exceeded
- DDoS protection triggered
- Resource usage limits reached

### Implementation
- Include Retry-After when the client can safely retry later
- Document rate-limit windows and expose limit headers when your API contract supports them

### Common Headers
- Retry-After
- RateLimit-Limit
- RateLimit-Remaining
- RateLimit-Reset

### Body
- Include a stable error code and the limit that was exceeded

### Pitfalls
- Use 503 for general service overload rather than a client-specific limit
- Avoid changing rate-limit semantics without updating API documentation
- Server overload (use 503 Service Unavailable)
- Authorization issues (use 403 Forbidden)
- Single slow request (use 408 Request Timeout)

## Client Perspective

### Pitfalls
- Do not retry immediately in a tight loop

## Examples

### API rate limit exceeded

Client exceeded 100 requests/hour limit, must wait 1 hour

**Request:**
```
GET https://api.example.test/api/data
```

**Response:**
```
429 Too Many Requests
Retry-After: 3600
Content-Type: application/json

{
  "error": "too_many_requests"
}
```

## Related Codes

- [503 Service Unavailable](/docs/503.md)