Back to list
429

Too Many Requests

4xx Client Error

.md

ELI5

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

Server perspective

Use 429 when a requester exceeds a rate limit or quota that applies to that client.

When to use

  • •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

How to respond

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

Headers to consider

  • •Retry-After
  • •RateLimit-Limit
  • •RateLimit-Remaining
  • •RateLimit-Reset

Response body

  • •Include a stable error code and the limit that was exceeded

Server-side 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)

Examples

API rate limit exceeded

Request:GET https://api.example.test/api/data
Response:429 Too Many Requests # Headers Retry-After: 3600 Content-Type: application/json # Body { "error": "too_many_requests" }

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

References

Related Status Codes

503

Service Unavailable

Our service is temporarily down for maintenance or overloaded. Please try again later.