503 Service Unavailable: what it means and how to fix it

02What causes a 503 error?

Six causes account for most 503s, and each leaves a different trace.

03How to tell which 503 you are seeing

Start with the response itself, then the logs of the component that sent it. A deliberate 503 usually carries clues: a Retry-After header, a branded page (whose branding shows whether the edge or the origin answered) or a matching log line.

In nginx, a rate-limit rejection appears in the error log as limiting requests, excess: 0.989 by zone "perip", followed by the client address and request. If those lines line up with the 503s, the server is healthy and your own limit is turning visitors away. Note that nginx's built-in page reads "503 Service Temporarily Unavailable"; the status code is the same.

# status line, Retry-After and the server that answered
curl -sI https://example.com/ | grep -iE '^(HTTP|retry-after|server)'

# WordPress maintenance flag left behind by an update
ls -la /var/www/html/.maintenance

# nginx rate limiting: count rejections and see which zone fired
grep -c 'limiting requests' /var/log/nginx/error.log
grep 'limiting requests' /var/log/nginx/error.log | tail -n 3

04When rate limiting returns 503

This is the 503 most often mistaken for an outage. nginx's limit_req and limit_conn modules use 503 as their default rejection status, so an over-tight limit makes a healthy site look down to exactly the users who use it most. The dedicated status for a client sending too much is 429 Too Many Requests, defined in RFC 6585, which may also carry Retry-After.

Return 429 for per-client limits and keep 503 for genuine capacity problems, so monitoring and people can tell the two apart at a glance. Google's crawlers treat both 429 and 5xx as a signal to slow down, so neither is a way to block crawling. Choosing sensible limits is covered in what rate limiting is.

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

server {
    location /login {
        limit_req zone=perip burst=20 nodelay;
        limit_req_status 429;
        # proxy_pass or fastcgi_pass as usual
    }
}

05How to serve a maintenance 503 with Retry-After

For planned work, 503 is the right status: it tells browsers, monitors and crawlers that the outage is temporary. Add Retry-After with either a number of seconds or an HTTP date, as RFC 9110 specifies, for example Retry-After: 600 or Retry-After: Fri, 31 Dec 1999 23:59:59 GMT.

Google's guidance is to use a 503 only for short interruptions of one or two days at most, and never to return 503 for robots.txt, because that blocks crawling of the whole site. The configuration below keeps robots.txt out of maintenance for that reason. Create the flag file to switch maintenance on and delete it to switch off, without a reload. The always parameter matters: without it nginx adds headers only to successful responses, so Retry-After would be missing from the 503.

location / {
    if (-f /var/www/maintenance.on) {
        return 503;
    }
    try_files $uri $uri/ =404;
}

location = /robots.txt {
    try_files $uri =404;        # never serve robots.txt as 503
}

error_page 503 /maintenance.html;
location = /maintenance.html {
    root /var/www/static;
    add_header Retry-After 600 always;
    internal;
}

06Can a DDoS attack cause 503 errors?

Yes, in three ways. An HTTP flood can exhaust an application's workers or a load balancer's queue, which then answers 503 because it has nowhere to send the request. Rate limiters tuned for normal traffic start rejecting real visitors along with the flood. And a protection layer in front of the site may itself answer some requests with 503 and Retry-After under extreme load, deliberately shedding work so the origin survives instead of collapsing.

The difference between a deliberate shed and a collapse matters. Shedding is selective and short; a collapse takes every page down and stays down. Filtering and capacity in front of the origin, as described in how to stop a DDoS attack, turn most floods into the first case. The guide to types of DDoS attacks explains which resource each kind of flood exhausts, and the signs of a DDoS attack separate a flood from an ordinary traffic spike.

07How to fix a 503 as the site owner

Fix the component that sent the 503, not the one that displayed it.

• Maintenance left on: remove the flag file or the plugin setting, after finishing or rolling back the update
• Rate limits too tight: count "limiting requests" lines, raise the rate or burst, and switch the rejection code to 429
• Empty backend pool: fix the failing health check, or the service behind it, before adding servers
• Stopped IIS application pool: find the crash in the Windows event log and fix it before starting the pool again, or rapid-fail protection will stop it again
• Overloaded queue: make requests faster or add capacity; raising queue limits only moves the wait
• Traffic surge or attack: cache what can be cached, filter abusive traffic upstream, and keep the origin address private

08What to do if you see a 503 as a visitor

A 503 is the site telling you to come back later. Wait for the time given on the page, or a few minutes, then reload; rapid repeated reloading can keep you inside a rate limit. If the site is down for everyone, nothing on your side will help. If only you get 503s while others do not, a VPN, a shared corporate address or a browser extension may be tripping a per-client limit.