# Rate Limiting — REST API Design

Source: https://www.geekswithgeeks.com/en/restapi/api-rate-limiting

> Protecting an API from abuse and runaway clients.

## Why limit requests

Without a cap, one misbehaving script, a retry storm, or a malicious actor can overwhelm your API and degrade it for everyone else. Rate limiting caps how many requests a key/user/IP can make in a window.

## Telling the client

Return `429 Too Many Requests` with headers so well-behaved clients can back off automatically.

```http
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1725448800
Retry-After: 30
```

## A leaking bucket

The **token bucket** algorithm fills a bucket with tokens at a steady rate; each request spends one. Short bursts drain saved-up tokens, but you can never sustain more than the fill rate — smooth, and simple to reason about.

**Quiz:** A client exceeds its rate limit. What should the API return?

- [ ] 403 Forbidden
- [x] 429 Too Many Requests
- [ ] 503 Service Unavailable

*Answer:* 429 Too Many Requests. 429 specifically signals rate limiting, ideally with a Retry-After header telling the client when to try again.