Home Server & Self-Hosting

Planned Maintenance with HTTP 503 - Make Temporary Downtime Honest

Planned Maintenance with HTTP 503 - Make Temporary Downtime Honest

Planned Maintenance with HTTP 503 - Make Temporary Downtime Honest

A maintenance page can look reassuring in a browser while saying the wrong thing to every client that cannot interpret its prose. If a requested article is replaced by “We will be back soon” but the response still carries 200 OK, the HTTP message says that the request succeeded and that the maintenance page is the requested representation.

That mismatch matters to more than search crawlers. API clients, monitors, caches, command-line tools, and browsers first receive a status and headers. The page body is for the person reading it; the HTTP metadata explains what happened to software.

For a short planned outage, 503 Service Unavailable can make those two layers agree. It is a small status code with a narrow promise: the service is unavailable now, and the condition is expected to be temporary. It does not promise an exact recovery time, and it is not automatically the best answer for every kind of maintenance.

What 503 Says

RFC 9110 defines 503 for a server that is currently unable to handle a request because of temporary overload or scheduled maintenance. The server may also send Retry-After to suggest how long the condition is expected to last.

The word temporary does important work. Compare several responses that can all produce an unhelpful page in a browser:

  • 200 OK says the request succeeded. A maintenance notice is not a successful copy of the article, dashboard, or API resource that was requested.
  • 404 Not Found says the origin did not find a current representation for that target. Planned downtime has not made every resource disappear.
  • 410 Gone communicates intentional, likely permanent unavailability. That is much stronger than “the database migration should finish soon.”
  • 503 Service Unavailable says the server cannot handle the request now because of a temporary condition.

A friendly body still belongs with the 503. It can explain what is unavailable, what remains available, when the next update is expected, and where a visitor can obtain help. The status is not a replacement for communication; it prevents the communication from contradicting the protocol.

Retry-After Is Guidance, Not an Appointment

The Retry-After field accepts either an HTTP date or a number of seconds:

Retry-After: Tue, 17 Nov 2026 02:00:00 GMT

Retry-After: 3600

The first form identifies a time; the second asks the user agent to wait that many seconds after receiving the response. Delay-seconds can be easier for a short window because it does not depend on writing a correctly formatted future date into the configuration.

Neither form schedules a retry. The RFC describes how long a user agent ought to wait, but a browser may simply display the page, a crawler may apply its own policy, and a custom client may ignore the field. Choose an honest estimate, not a false guarantee. If the end time is unknown, a clear page without invented precision is better than a confident but meaningless timestamp.

A Small Nginx Pattern

The following pattern uses a flag file as the switch. It is intentionally small, but it still needs to be adapted to the site's existing locations, document root, proxy or FastCGI rules, and deployment process.

server {
    server_name example.com;
    root /var/www/example.com/public;

    error_page 503 /maintenance.html;

    location = /robots.txt {
        try_files /robots.txt =404;
    }

    location / {
        if (-f /var/www/example.com/maintenance.flag) {
            return 503;
        }

        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /maintenance.html {
        internal;
        add_header Retry-After "3600" always;
        add_header Cache-Control "no-store" always;
    }

    # The site's existing PHP location belongs here.
}

Nginx documents both file-existence tests in if and return with a chosen status. When the flag exists, request processing stops with 503. The error_page directive then performs an internal redirect to the static page while preserving the error status because the configuration does not replace it with =200.

The exact robots.txt location is evaluated separately from the general location /, so it remains available. That exception is not a universal HTTP requirement. It follows Google Search Central's guidance for a temporarily disabled site: do not answer the robots file with 503, because doing so blocks Google's crawling.

Why the Maintenance Location Is Internal

The internal directive prevents a visitor from requesting /maintenance.html directly. Nginx can reach it through the error-page redirect, but a normal external request cannot use that URI as if it were a public page. This keeps one useful invariant: the maintenance representation accompanies an actual maintenance response.

Why the Headers Use always

By default, Nginx's add_header directive only applies to a documented list of response codes, and 503 is not in that list. The always parameter is therefore necessary here.

Scoping these headers to the maintenance location is just as important. A server-level Retry-After: 3600 could leak onto healthy responses after maintenance ends. Nginx header inheritance also deserves attention: defining any add_header at a child level can change which parent headers are inherited, depending on configuration and Nginx version. If the normal server adds security headers, test the final maintenance response rather than assuming they survived.

Cache-Control: no-store is a conservative choice for this static error response. It reduces the risk of a cache continuing to serve yesterday's maintenance page after the service has recovered. MDN cautions that caching headers on a 503 need special attention; this example is operational guidance, not a rule that every 503 response must use the same cache policy.

Keep the Page Independent of the Failing Stack

A maintenance page routed through the same PHP application, database, asset pipeline, and third-party scripts under maintenance has too many ways to fail. Google recommends static HTML with minimal off-page resources for a whole-site closure. A self-contained page might be as modest as this:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Short maintenance window</title>
  <style>
    body { max-width: 42rem; margin: 12vh auto; padding: 1rem;
           font: 1.1rem/1.6 system-ui, sans-serif; }
  </style>
</head>
<body>
  <h1>Short maintenance window</h1>
  <p>This service is temporarily unavailable.</p>
  <p>The next status update is expected by 02:00 UTC.</p>
</body>
</html>

The time in the body and the header should tell a consistent story. If the estimate changes, update both. Avoid a JavaScript countdown that silently reaches zero while the outage continues; plain language can acknowledge uncertainty more honestly.

Test the Transition, Not Just the File

A valid-looking Nginx snippet is not evidence that a particular server block behaves correctly. Validate the assembled configuration before reloading it:

sudo nginx -t
sudo systemctl reload nginx

Then inspect a representative public URL. The status and headers are the main evidence:

curl -i https://example.com/an-existing-page
curl -i https://example.com/robots.txt

During maintenance, the first response should show 503, the intended Retry-After, the cache policy, and the static body. The robots file should show its normal successful response. Test a POST or API route too if the site accepts writes; maintenance must not accidentally process a state-changing request behind the friendly page.

Recovery needs its own test. Remove the flag, reload only if the surrounding setup requires it, and request the same URLs again. The normal page should return its normal status, the maintenance body should be gone, and Retry-After should not remain. Also check from outside any CDN or reverse-proxy cache when that layer is part of the route.

When Full-Site 503 Is the Wrong Tool

A whole-site maintenance switch is simple, but simplicity can hide unnecessary damage. If articles, documentation, and account history can remain readable while checkout or publishing is paused, preserving that read-only surface is usually more useful to visitors. Google likewise recommends limiting functionality instead of disabling an entire site when possible.

A short 503 window also should not become a vague long-term holding pattern. Google warns that disabling a whole site for more than a very short period can significantly affect its presence in Search, even when implemented properly. That statement describes Google's systems, not a universal ranking timer, and it offers no guaranteed harmless duration.

Finally, planned maintenance and overload share the same status but not the same control system. A manually created flag can represent a scheduled database migration. It does not detect CPU pressure, choose which traffic to shed, or recover an unhealthy upstream. Automatic overload protection needs monitoring, thresholds, and failure behavior beyond this page.

Conclusion

A maintenance page has two audiences. People need a concise explanation and a realistic next update. Software needs a response whose status and headers describe the same temporary failure.

For a short whole-site outage, 503 Service Unavailable, a carefully estimated Retry-After, and a static Nginx-served body can align those audiences. The pattern remains incomplete until both entry and recovery have been tested. The more useful question is not merely “how do I turn maintenance mode on?” but “how much of the site truly needs to become unavailable at all?”

References

  1. 503 Service Unavailable, RFC 9110 - RFC Editor
  2. Retry-After, RFC 9110 - RFC Editor
  3. ngx_http_core_module: error_page and internal - Nginx
  4. ngx_http_rewrite_module: if and return - Nginx
  5. ngx_http_headers_module: add_header - Nginx
  6. Temporarily Pause or Disable a Website - Google Search Central
  7. 503 Service Unavailable - MDN Web Docs