503 Service Unavailable
The server is temporarily unable to handle the request, because it is overloaded or deliberately down for maintenance. The condition is expected to clear.
At a glance
- Status code
- 503 Service Unavailable
- Class
- 5xx, server error, the request looked fine and the server failed
- Defined in
- RFC 9110
- Cacheable by default
- by explicit headers only
- Response body
- Should explain and carry Retry-After.
In detail
503 is the only 5xx that carries an explicit promise of impermanence. Retry-After turns that promise into something a client can act on.
The right code for planned maintenance. Search engines treat a 503 with Retry-After as a temporary outage and keep the URL indexed, which a 500 does not guarantee.
Always send Retry-After during maintenance. Without it, crawlers and clients have to guess, and the conservative guess is to assume the page is gone.
Examples
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/html
<h1>Back shortly</h1>Things that catch people out
- A 503 that is really permanent damages search visibility once crawlers stop believing the Retry-After.
- Load shedding that returns 503 must be cheaper than serving the request, or it does not shed anything.
- Do not cache a 503 without no-store, or the maintenance page outlives the maintenance.
Try it: HTTP Request Builder
Build a request with any method, headers and body, send it, and read the status line the server returns.
HTTP Request Builder
LOCAL · Browser-OnlyBuild and test HTTP requests with custom headers and body
Authentication
Headers
Generate Code
curl -X GET 'https://api.example.com/endpoint' \
-H 'Content-Type: application/json'Showing a sample URL. Enter your endpoint above to update the snippet.
Related HTTP status codes
All http status codes →502 Bad Gateway
A proxy or load balancer got an invalid response from the upstream server it was relaying to. The failure is behind the thing that answered you.
504 Gateway Timeout
A proxy gave up waiting for the upstream server to answer. The upstream may still be working on the request.
429 Too Many Requests
The client has sent too many requests in a given period. The Retry-After header says how long to wait before trying again.
505 HTTP Version Not Supported
The server refuses the major HTTP version used in the request line.
506 Variant Also Negotiates
A server configuration error in transparent content negotiation: a chosen variant is itself configured to negotiate, creating a loop.
507 Insufficient Storage
The server cannot store the representation needed to complete the request, because it is out of space.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL