503 Service Unavailable
The server cannot handle the request right now, usually because it is overloaded or down for maintenance. Try again later.
What 503 Service Unavailable means
503 is for temporary conditions. The server can send Retry-After with a number of seconds or a date to say when it expects to be back.
It is the right status for planned maintenance pages. Search engines treat a short 503 as temporary and keep the page, while a maintenance page served with 200 could end up indexed.
Common causes
- Planned maintenance or a deploy in progress.
- More traffic than the available servers or workers can handle.
- No healthy backends left behind a load balancer because the app is failing health checks.
- A dependency such as the database is down, and the app reports itself unavailable.
How to fix 503 Service Unavailable
- As a visitor, wait and retry, and check the site's status page.
- As a client, honour Retry-After and back off instead of retrying in a tight loop.
- As the owner, check health checks, autoscaling, worker limits (PHP-FPM pm.max_children, Gunicorn workers) and CPU and memory usage.
- Serve maintenance pages with 503 and a Retry-After header.
Headers that go with it
Retry-After
Example response
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/plain; charset=utf-8
503 Service UnavailableHow to check for a 503 response
cURL
# Print only the status code
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/JavaScript (Node.js)
const res = await fetch("https://example.com/");
if (res.status === 503) {
console.log(res.status, res.statusText);
}Python
import requests
res = requests.get("https://example.com/")
if res.status_code == 503:
print(res.status_code, res.reason)Go
res, err := http.Get("https://example.com/")
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode == 503 {
fmt.Println(res.Status)
}Specification
503 Service Unavailable is defined in RFC 9110, section 15.6.4.
Related status codes
- 502
A server acting as a gateway or proxy got an invalid response, or no usable response, from the upstream server behind it.
- 504
A gateway or proxy waited too long for a response from the upstream server and gave up before the page was ready.
- 429
You sent too many requests in a short time and hit a rate limit. Wait, then retry, ideally after the Retry-After time.