503 Service Unavailable
The server is currently unable to handle the request. This is usually a temporary condition — either the server is overloaded, undergoing maintenance, or a dependent service is down. Unlike 500 (a bug), 503 is a deliberate, expected temporary state. Should include Retry-After header.
What can I do?
- The website is temporarily down for maintenance or is very busy. Try again in a few minutes.
How to debug & fix
- Return 503 with Retry-After header during maintenance windows
- Use 503 as the health check failure response for load balancers
- Implement circuit breakers for downstream dependencies
- Set up a static maintenance page that your reverse proxy can serve when the app is down
- Return Retry-After so load balancers and clients know when to retry — both seconds (integer) and HTTP-date formats are valid.
- Serve a static maintenance page from your reverse proxy so users see a friendly message even when your app is fully down.
Code Example
// Maintenance mode middleware
const MAINTENANCE = process.env.MAINTENANCE_MODE === 'true';
app.use((req, res, next) => {
if (MAINTENANCE) {
return res.status(503)
.set('Retry-After', '3600')
.json({ error: 'Service Unavailable', message: 'Scheduled maintenance until 14:00 UTC' });
}
next();
});Related Status Codes
How HTTP Status Codes Work
Every HTTP response carries a three-digit status code that tells the client — browser, API consumer, or search-engine crawler — exactly what happened. The first digit defines the class: 1xx informational (request in progress), 2xx success, 3xx redirection, 4xx client error (bad request, missing auth, not found), and 5xx server failure.
Status codes are standardised in RFC 9110 (HTTP Semantics, 2022). Extensions like WebDAV (RFC 4918) and rate-limit headers (RFC 6585) added codes beyond the core set. When a client receives an unrecognised code, the rule is to treat it as the generic x00 of its class.
Why the Right Code Matters
Semantically correct codes help search engines index accurately (301 passes link equity; 410 removes pages faster than 404), allow API clients to implement correct retry logic (429 + Retry-After, 503 + Retry-After), and let monitoring systems distinguish bugs (500) from load issues (503) from auth failures (401/403).
Looking up a different status code? The full reference covers all HTTP codes with causes, fix guides, and copyable code examples for Node.js and Python.
Browse the full HTTP Status Code reference →