Status codes · one code503Service Unavailable

What a 503 Service Unavailable response means, who is at fault, what a visitor should do and what the server owner should do.

Open the reference on this code
What is happening

The server is alive and says «not right now»

server reached pm.max_children setting (5), consider raising it

A 503 has two entirely different causes, and confusing them is expensive. The first is deliberate maintenance, and then 503 is the correct answer. The second is running out of worker processes: requests queue up with nobody to serve them, and the line above appears in the log. The browser shows the same «Service Temporarily Unavailable» either way.

Code
Who is at faultServer error
Class5xx Server error
Headers
Retry-Afterwhen to try again
01

What to do

If it is someone else's site

Come back later — the server is running and says itself that it is temporarily unavailable. If the response carries Retry-After, it states when to return; hammering refresh will not speed anything up.

If it is your server

Take a site down for maintenance with a 503 and a Retry-After header — not with a stub page returning 200 and not with a redirect to a «back soon» page: in those cases a search engine treats the stub as real content and may drop pages from the index, and recovery takes weeks. If the 503 comes from exhausted workers rather than from you, do not raise the limit blindly: work out how much memory one process takes, or the server will start swapping and get slower than it was.

02

Easily confused with

500Internal Server Error

the application crashed on a request rather than being taken out of service deliberately.

500
429Too Many Requests

a limit aimed at you personally rather than the service being unavailable as a whole.

429
502Bad Gateway

the upstream is unreachable at all; here the server answers and states the reason.

502
03

How to check

curl -sI https://example.com/ | grep -iE 'http/|retry-after'

the code and the return time at once: without Retry-After a maintenance window is incomplete

grep max_children /var/log/php8.3-fpm.log | tail -n 5

whether the pool is hitting its process limit — the second cause of a 503

Find another code

The reference holds sixty-four codes searchable by number, name and meaning — plus a breakdown of confusing pairs such as 401 and 403.

Open the reference on this codeAll codes

Updated

«» added to favorites