HTTP 503 Service Unavailable

What does HTTP 503 mean?

The server is temporarily unable to handle the request. Overload or planned maintenance. Add a Retry-After header so clients and crawlers know when to come back.

5xx Server error: The request looked valid, but the server failed to fulfil it. The fix is on the server side.

Common causes of a 503 error

• Planned maintenance mode.
• Server overloaded or out of workers.
• Autoscaling not keeping up with a traffic spike.

How to fix 503 Service Unavailable

• Serve maintenance pages with 503 and Retry-After, not 200.
• Scale capacity, add caching, or queue work.

How to find the cause of a 503

A 503 means the server is deliberately refusing work, usually because of overload or maintenance.

uptime
free -h
sudo systemctl status your-app
ls -la .maintenance

High load or no free memory points to overload, so add capacity, caching or rate limiting. On WordPress, a leftover .maintenance file after a failed update keeps the whole site in maintenance mode, and deleting it brings the site back.

503 and SEO

The correct status for maintenance: Google keeps pages indexed for a short 503 period and retries later. Days of 503 will start to remove pages.

Example response

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

How to return a 503 response

Node.js (Express)

res.status(503).json({ error: 'Service Unavailable' });

PHP

http_response_code(503);

Python (Flask)

return {'error': 'Service Unavailable'}, 503

Go (net/http)

w.WriteHeader(503)

nginx

return 503;

Related status codes

• 500 Internal Server Error — The server hit an unexpected condition and could not complete the request.
• 502 Bad Gateway — A gateway or proxy got an invalid response from the upstream server.
• 504 Gateway Timeout — A gateway or proxy did not get a response from the upstream server in time.
• 429 Too Many Requests — The client sent too many requests in a given amount of time.

Check which status code a URL returns with the HTTP header checker.