Tech

Explainer

Updated

What does the HTTP 429 status code mean?

Key facts

A 429 response may include a Retry-After header that tells the client how long to wait, as a date or a number of seconds, before it makes a new request.

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:

FormExampleHow to read it
Seconds3600 (the RFC 6585 example)Wait 3,600 seconds, or one hour, after receiving the response
Seconds120 (an RFC 9110 example)Wait 120 seconds, which RFC 9110 calls 2 minutes
HTTP-dateFri, 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.

How the server counts requests is up to the server

RFC 6585 does not define how the origin server identifies the user, nor how it counts requests. It gives examples: a server can count requests per resource, across the entire server, or even among a set of servers, and it might identify the user by authentication credentials or by a stateful cookie.

A server does not have to send 429

The security considerations of RFC 6585 say that when a server is under attack or receiving a very large number of requests from a single party, answering each one with a 429 consumes resources. So servers are not required to use the code, and when limiting resource usage it may be more appropriate to just drop connections or take other steps. The introduction to RFC 6585 also says its status codes are optional and servers cannot be required to support them.

How 429 compares with 503, 413 and 431

Other codes also come up when a server limits what it will accept. This table summarizes each definition and what it says about Retry-After.

CodeWhat its definition saysRetry-After in the definition
429 Too Many RequestsThe user has sent too many requests in a given amount of timeThe response may include it
503 Service UnavailableThe server cannot handle the request now because of a temporary overload or scheduled maintenanceThe server may send it
413 Content Too LargeThe request content is larger than the server is willing or able to processThe server should send it if the condition is temporary
431 Request Header Fields Too LargeThe request's header fields are too largeNot named

The 429 and 431 rows come from Sections 4 and 5 of RFC 6585, the 503 row from Section 15.6.4 of RFC 9110 and the 413 row from Section 15.5.14 of RFC 9110. The codes sit in different classes: RFC 9110 puts 4xx codes such as 429, 413 and 431 in the Client Error class and 5xx codes such as 503 in the Server Error class. A separate page explains 503 Service Unavailable.

What happens when a client does not know 429

RFC 9110 says a client must understand the class of any status code, as shown by its first digit, and treat an unrecognized code as equivalent to the x00 code of that class. An older client that does not know 429 therefore handles it as a 400 Bad Request. The introduction to RFC 6585 relied on the same rule, saying clients treat unknown codes as a generic error of the same class, so the new codes can be safely deployed by existing servers.

Can a 429 be cached?

No. RFC 6585 says responses with the 429 status code must not be stored by a cache, and it sets the same rule for 428, 431 and 511.

What changed and when

RFC 6585 was published in April 2012 as a Standards Track document that updates RFC 2616, and it added four codes: 428 Precondition Required, 429 Too Many Requests, 431 Request Header Fields Too Large and 511 Network Authentication Required. Its introduction says the codes were added to improve interoperability and avoid confusion when other, less precise status codes are used. RFC 9110, published in June 2022 on the Standards Track, obsoletes RFC 7231 and is now where Retry-After is defined, in Section 10.2.3; it does not define 429 itself and points to RFC 6585 for additional status codes related to capacity limits. The IANA registry lists 429 Too Many Requests with the reference RFC 6585 and shows its last update as September 15, 2025.

Have another question?