The HTTP 429 (Too Many Requests) status code means that the user has sent too many requests in a given amount of time, which RFC 6585, the IETF standard that defines the code, calls rate limiting. In the words of Section 4 of RFC 6585, "The 429 status code indicates that the user has sent too many requests in a given amount of time ("rate limiting")."
What a 429 response should contain
RFC 6585 says the response representations should include details explaining the condition, and may include a Retry-After header indicating how long to wait before making a new request. Its own example response carries the header Retry-After: 3600 and a page that tells the user the site allows 50 requests per hour per logged in user.
A 429 is a client error. The 4xx (Client Error) class in RFC 9110 indicates that the client seems to have erred, and except when responding to a HEAD request, the server should send a representation explaining the error situation and whether it is a temporary or permanent condition.
How the Retry-After header works with a 429
Section 10.2.3 of RFC 9110 says servers send the Retry-After header field to indicate how long the user agent ought to wait before making a follow-up request, and that its value can be either an HTTP-date or a number of seconds to delay after receiving the response. The two forms look like this:
| Form | Example | How to read it |
|---|---|---|
| Seconds | 3600 (the RFC 6585 example) | Wait 3,600 seconds, or one hour, after receiving the response |
| Seconds | 120 (an RFC 9110 example) | Wait 120 seconds, which RFC 9110 calls 2 minutes |
| HTTP-date | Fri, 31 Dec 1999 23:59:59 GMT (an RFC 9110 example) | Wait until that moment, in UTC |
RFC 9110 says a delay-seconds value is a non-negative decimal integer, and its date and time section says an HTTP-date value represents time in Coordinated Universal Time (UTC). The header is optional on a 429: RFC 6585 says the response "MAY" include it.