Tech

Explainer

Updated

What does the HTTP 503 status code mean?

Key facts

A server may send a Retry-After header with a 503 to say how long the service is expected to be unavailable, as a date or a number of seconds.

The HTTP 503 (Service Unavailable) status code means that the server is currently unable to handle the request because of a temporary overload or scheduled maintenance, according to RFC 9110, the IETF standard that defines HTTP semantics. In the words of Section 15.6.4 of RFC 9110, "The 503 (Service Unavailable) status code indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay."

A 503 is meant to be temporary

The definition ties 503 to a condition that will likely be alleviated after some delay. The 5xx (Server Error) class as a whole indicates that the server is aware that it has erred or is incapable of performing the requested method, and RFC 9110 says that, 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 503

RFC 9110 says the server may send a Retry-After header field with a 503 to suggest an appropriate amount of time for the client to wait before retrying the request. Section 10.2.3 says that when Retry-After is sent with a 503 response, it indicates how long the service is expected to be unavailable to the client. The value can be either an HTTP-date or a number of seconds to delay after receiving the response, and the standard gives these two examples:

FormExample from RFC 9110How to read it
HTTP-dateFri, 31 Dec 1999 23:59:59 GMTWait until that moment, in UTC
Seconds120Wait 120 seconds after receiving the response

RFC 9110 says an HTTP-date value represents time in Coordinated Universal Time (UTC), and its Retry-After section says a delay-seconds value is a non-negative decimal integer. The header is optional: the definition says the server "MAY" send it.

How 503 compares with 500, 502, 504 and 429

Several codes can appear when a site is down or busy. RFC 9110 defines the 5xx codes in this table, and RFC 6585 defines 429, which is a client error in the 4xx class.

CodeWhat its definition saysRetry-After in the definition
500 Internal Server ErrorAn unexpected condition prevented the server from fulfilling the requestNot named
502 Bad GatewayA gateway or proxy received an invalid response from an inbound serverNot named
503 Service UnavailableThe server cannot handle the request now because of a temporary overload or scheduled maintenanceThe server may send it
504 Gateway TimeoutA gateway or proxy did not receive a timely response from an upstream serverNot named
429 Too Many RequestsThe user has sent too many requests in a given amount of timeThe response may include it

The 500, 502, 503 and 504 rows are summarized from Sections 15.6.1 to 15.6.5 of RFC 9110, and the 429 row from Section 4 of RFC 6585. Separate pages explain 502 Bad Gateway and 504 Gateway Timeout.

An overloaded server does not have to send 503

RFC 9110 adds a note: "The existence of the 503 status code does not imply that a server has to use it when becoming overloaded." The same note says some servers might simply refuse the connection instead.

Can a 503 be cached?

Not by heuristic expiration. The overview of status codes in RFC 9110 gives the heuristically cacheable codes in that specification, by way of example, as 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 and 501, and says all other status codes are not heuristically cacheable, which leaves 503 outside the list. For 429, RFC 6585 goes further and says responses with that code must not be stored by a cache.

What changed and when

RFC 7231, published in June 2014, defined 503 in Section 6.6.4 with the same wording and the same note about overloaded servers, and defined Retry-After in Section 7.1.3. RFC 9110 was published in June 2022 on the Standards Track, carries the number STD 97 and obsoletes RFC 7231, as its header shows; the definition of 503 moved to Section 15.6.4 and Retry-After to Section 10.2.3. The IANA registry now points code 503 to RFC 9110, Section 15.6.4, lists 429 Too Many Requests with the reference RFC 6585, and shows its last update as September 15, 2025.

Have another question?