Service Unavailable

Overview

503 Service Unavailable means the server is temporarily unable to handle the request due to overload or maintenance. The server is alive but cannot take requests right now — an intentional or temporary condition.

A well-formed 503 uses a Retry-After header to say when to try again. During planned deploys or maintenance it also serves as a proper "we're down for maintenance" page for users.

When it happens

• A traffic spike overloads the server and exhausts its workers
• The service is taken down during a planned maintenance window
• The autoscaler is still adding capacity
• A dependency failure fails health checks and the instance is pulled out of rotation

Request / Response example

GET / HTTP/1.1
Host: www.example.com

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/html

<h1>503 Service Unavailable</h1>
<p>We are down for maintenance. Please try again shortly.</p>

In code

app.use((req, res, next) => {
  if (process.env.MAINTENANCE === '1') {
    return res.status(503).set('Retry-After', '120').send('Under maintenance');
  }
  next();
});

location / {
  if (-f /etc/nginx/maintenance.on) {
    return 503;
  }
  proxy_pass http://backend;
}
error_page 503 /maintenance.html;

Notes

• 503 is a transient error, so retrying is valid — honor Retry-After to give the server time to recover.
• When serving a maintenance 503, include Retry-After and keep it short so search engines do not drop the page.
• 503 (the server itself cannot accept) differs from 502/504 (a backend response problem or delay); if Retry-After is present it is usually a 503-class case.

Related status codes

Related headers

Specification