Planned maintenance done right: 503, Retry-After and a maintenance page

How to take a site offline on purpose without hurting SEO or confusing clients: return 503 with Retry-After, nginx and app examples, and how to keep monitoring quiet.

· 7 min read · By the Spot Downtime team

Sometimes a site has to go down on purpose: a database migration, a server move, a big deploy. The usual shortcut is to swap in a friendly “We'll be back soon” page. If that page is served with a 200 OK, you have told every crawler, API client and uptime check that your real content is gone and a page saying “back soon” is what the URL now contains.

The correct signal is 503 Service Unavailable, ideally with a Retry-After header. This post shows how to send both, and how to keep the maintenance window from triggering a pile of false alarms.

Why 503 and not 200 or 404

  • 200 with a maintenance page. Search engines may index the maintenance text as the page's content. API clients parse the HTML as if it were data and fail in confusing ways. Monitors report the site as up.
  • 404 or 410. These say the resource is missing, possibly for good. A 410 in particular invites removal from search results. Not what you want for a 20-minute outage.
  • 503. The server is temporarily unable to handle the request. Clients know to try again later, and crawlers treat it as a temporary condition rather than a change to the page.

A 503 can also mean an overloaded or crashing backend, which is covered in 502, 503 and 504 errors. Here the 503 is deliberate.

What Retry-After does

Retry-After tells the client when to come back. It takes either a number of seconds or an HTTP date:

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

# or a fixed time
Retry-After: Wed, 04 Nov 2026 22:00:00 GMT

Well-behaved API clients and some crawlers use it to schedule their next attempt instead of hammering you. Not every client honors it, so treat it as a hint, not a guarantee. Pick a number you can keep: if you say 30 minutes and the work takes two hours, extend the value or remove the header rather than leaving a promise you broke.

Keep it short

A 503 is meant for short, temporary downtime. If a site returns 503 for days, search engines can start treating the pages as gone and drop them from the index. For anything longer than a day, plan a different approach, such as serving a read-only version.

Serving a maintenance page with nginx

The pattern: check for a flag file, return 503 while it exists, and show a static HTML page for that error. To start maintenance, create the file. To end it, delete the file. No config reload is needed.

server {
    listen 80;
    server_name example.com;

    error_page 503 @maintenance;

    location / {
        if (-f /var/www/maintenance.on) {
            return 503;
        }
        proxy_pass http://app_backend;
    }

    location @maintenance {
        root /var/www/maintenance;
        rewrite ^ /maintenance.html break;
        add_header Retry-After 1800 always;
    }
}

The always flag matters. Without it, nginx only adds add_header values to success and redirect responses, so your header would vanish from the 503. Test the config and reload once, then toggle maintenance by file:

sudo nginx -t && sudo systemctl reload nginx

touch /var/www/maintenance.on      # start maintenance
rm /var/www/maintenance.on         # end maintenance

curl -I https://example.com/       # expect HTTP/1.1 503 and Retry-After

Inside an if block, return is one of the few directives that is safe to use in nginx, which is why the example does nothing else there.

Doing it in the application

If you do not control the web server, a small middleware does the same job. This Express example reads a flag from the environment and lets the health endpoint through so a load balancer does not pull the instance out:

app.use((req, res, next) => {
  if (process.env.MAINTENANCE === "1" && req.path !== "/healthz") {
    res.set("Retry-After", "1800");
    return res.status(503).type("html").send(maintenancePage);
  }
  next();
});

For JSON APIs, return a JSON body with the same status instead of HTML, so clients can parse it:

HTTP/1.1 503 Service Unavailable
Retry-After: 1800
Content-Type: application/json

{"error": "maintenance", "message": "Back at 22:00 UTC."}

Checklist for the maintenance page

  1. Self-contained. Inline the CSS or use a tiny file. If the page links to assets served by the app you are upgrading, it renders unstyled or not at all.
  2. Say when you expect to be back, in plain words and a time zone. Link to your status page hosted elsewhere, so people can follow progress.
  3. Do not cache it. Send Cache-Control: no-store or short caching so a CDN does not keep serving the maintenance page after you finish.
  4. Keep a back door. Let your own IP or a health check path through so you can verify the new version before reopening.
  5. Test the exit. After removing the flag, check the home page, a deep link and an API route return normal responses with curl -I.

Telling your monitoring about it

A monitor cannot know that a 503 is intentional. During a planned window it will do its job and open an incident, page the on-call person and drag down your uptime figure. There are two sensible ways to handle that:

  • Pause or schedule maintenance for the affected monitors for the window, so no alerts fire and the downtime is not counted as an outage. In Spot Downtime you can schedule maintenance by asking an assistant connected through the Claude connector, for example before a deploy.
  • Leave monitoring on if you want proof the page worked. A 503 at the expected time is exactly what a correct maintenance page should produce.

Either way, watch the end of the window. The failure that bites teams is the maintenance flag staying on after the work is done, or a cached 503 lingering in a CDN. A monitor that is unpaused right after the window, or a website monitor with a keyword check for a phrase that only appears on the real page, catches that within a check interval. See also the website down checklist if it does not come back as planned.

HTTP headers checkerConfirm your site returns 503 and Retry-After, and that the headers are what you expect.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading