503 Service Unavailable

Server error: the request may be fine, but the server failed to carry it out.

When a server should send it. When the server is temporarily unable to handle requests: maintenance, overload, every backend down. Add Retry-After when you know how long it will last. For planned maintenance this is the correct code for every URL, rather than a 200 maintenance page.

Common causes. Maintenance, overload or every backend being down.

What to do. Retry later, after the Retry-After time if given. A planned outage should return 503 so search engines do not drop the pages.

Browsers and HTTP clients. Browsers show the body. Clients and crawlers treat it as temporary and come back later.

Google Search. Googlebot treats 5xx responses as a sign of trouble and temporarily slows its crawl rate. Already indexed URLs are kept at first, but are dropped if the errors continue. This makes 503 with Retry-After the right response for planned maintenance; a long outage still ends with pages dropped. Source: Google Search Central, How HTTP status codes, and network and DNS errors affect Google Search.

Caching. Not cacheable by default (RFC 9110 section 15.1 does not list it). A cache stores it only when the response says so with Cache-Control or Expires.

HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Type: text/html; charset=utf-8

Service Unavailable

location /example {
    add_header Retry-After '3600' always;
    return 503;
}

Header always set Retry-After "3600"
RewriteEngine On
RewriteRule ^example$ - [R=503,L]

header('Retry-After: 3600');
http_response_code(503);
echo 'Service Unavailable';
exit;

res.writeHead(503, { 'Retry-After': '3600', 'Content-Type': 'text/plain' });
res.end('Service Unavailable');

# in a view function
return 'Service Unavailable', 503, {'Retry-After': '3600'}