What it means
Rate limiting. Send Retry-After - without it a well-behaved client has to guess, and the usual guess is to retry immediately, which is precisely what you were trying to stop.
- Class
- 4xx Client error
- Defined in
- RFC 6585 §4
- Cached by default
- No
When you receive a 429
- You hit a rate limit. Wait for the time in
Retry-After- seconds, or an HTTP date - before trying again. - With no
Retry-After, back off exponentially with some random jitter rather than retrying at once. - Find out whether the limit is per key, per IP or per endpoint. Headers such as
X-RateLimit-Remainingusually say.
When you send a 429
- When one client exceeds its allowance.
- Include
Retry-After, and ideally the limit, what remains and when it resets. - For an overload that is not about one client,
503is the code.
On the wire
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Content-Type: application/json
{"error": "rate_limited", "detail": "100 requests per minute - try again in 30 seconds"}