HTTP 503 Maintenance Pages: Keep the Status Honest
A helpful maintenance page still needs an honest HTTP response. Preserve 503, verify Retry-After and cache behavior, then prove the real application returns.
DM
Suppose you've prepared a short maintenance window. The replacement page looks good: a calm explanation, a retry message, no broken layout. Then you inspect its response and find 200 OK. In this hypothetical deployment, the design is ready but the protocol is telling callers that the requested service succeeded.
Return HTTP 503 for temporary unavailability, keep that status when serving the maintenance body, and verify the response through the public route. Add a realistic retry hint when you can, choose a cache policy deliberately, and rehearse removing the maintenance response. A nice page is only one part of the contract.
Start with what the caller needs to know
RFC 9110 defines 503 Service Unavailable for temporary overload or scheduled maintenance. It permits a Retry-After field. That field can contain a delay in seconds after receipt or an HTTP date; it describes an expectation, not a reservation that makes the next attempt succeed.
For the imagined maintenance window, the response might look like this. The 120-second value is illustrative; don't copy it as a recovery promise.
HTTP/1.1 503 Service Unavailable
Content-Type: text/html; charset=utf-8
Retry-After: 120
Cache-Control: no-store
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Temporarily unavailable</title>
<h1>We're carrying out maintenance</h1>
<p>Please try again shortly.</p>
</html>The status tells software the requested work wasn't served successfully. The body explains the situation to a person. For an API route, keep the documented error format instead of substituting an HTML page that a JSON client cannot parse. Use the appropriate content type and preserve the same temporary-failure meaning.
A retry hint also doesn't make a write safe to repeat. The caller still needs its operation-identity, reconciliation and retry-budget policy. The HTTP 429 retry guide covers the client-side waiting decision; this article focuses on the response your service emits.
Serve a custom page without converting the error into success
NGINX's error_page reference distinguishes an internal error-page redirect from an explicit status override such as =200. For this maintenance response, keep the original 503. Don't redirect every request to a separate page that simply returns 200.
Here's an illustrative, dedicated staging server block to put inside NGINX's http context. It deliberately has no application upstream: every ordinary route is unavailable. Create /srv/www/maintenance.html with the HTML body above, readable by the NGINX worker, before rehearsing it.
server {
listen 8080;
server_name staging.example;
error_page 503 /maintenance.html;
location / {
return 503;
}
location = /maintenance.html {
internal;
root /srv/www;
default_type text/html;
charset utf-8;
add_header Retry-After 120 always;
add_header Cache-Control "no-store" always;
}
}The error handler serves the local file while retaining 503. internal prevents clients from using that file location directly; an external request to it receives 404. If the file is missing or unreadable, handling can fail and the final status can change. Check the file and the actual response rather than assuming the configuration guaranteed your intended result.
The add_header documentation matters here: 503 is outside its ordinary status list, so always is needed to attach these fields to this error response. We put them in the location serving the body. In a larger configuration, inspect header inheritance and existing security headers before adding location-level directives.
This is a staging example, not a complete production TLS or routing configuration. Don't replace a live server block wholesale. Decide which application routes should be unavailable and preserve separately required control paths, certificate validation routes and monitoring semantics. A maintenance page should not accidentally turn a liveness check into a restart trigger.
Treat caching as part of the exit plan
For this short-lived example, Cache-Control: no-store is a deliberate choice. RFC 9111's response directive tells private and shared caches not to store the response. It doesn't prove that every intermediary follows your intended policy or remove an older cached page.
Check any CDN or managed ingress in front of the origin: it may apply an error-page policy, replace a body or use existing cached content. Don't infer the public behavior from the origin configuration alone. Keep the explanatory page self-contained where practical, so its stylesheet or script doesn't depend on the application currently under maintenance.
Check the maintenance state and the restored state
Use a harmless read-only staging route that normally returns an identifiable application response. Inspect a GET through the public hostname first. This command displays headers and discards the body; make a separate request in your browser or test client to inspect the body too.
curl --silent --show-error --max-time 10 \
--dump-header - --output /dev/null \
https://staging.example/reports/latest
# Inside the VM, for the illustrative HTTP listener above:
curl --silent --show-error --max-time 10 \
--header 'Host: staging.example' \
--dump-header - --output /dev/null \
http://127.0.0.1:8080/reports/latestReplace the example hostname, route and port with your controlled staging values. The curl manual documents these options. We intentionally inspect the received status; curl completing a transfer isn't the same as the application being available. The curl status-check guide explains that distinction.
Use these proposed acceptance checks. They are a rehearsal plan, not results from a deployment tested for this article.
- With maintenance enabled, the chosen public route returns 503, the intended body and the chosen Retry-After and Cache-Control fields. Compare the local origin result if a proxy sits in front.
- Request an API route with its real client and confirm that its error format still matches the API contract. Check required monitoring routes separately.
- In staging, exercise a missing maintenance-file failure and confirm that your check detects the wrong status or body. Restore the file afterward.
- Remove the maintenance routing, then repeat the same public request. Confirm the real application content and expected normal status return, with the temporary retry hint gone. Check another route and the actual client workflow.
If the origin has recovered but the public route still serves maintenance, investigate the intermediary path and cache state before declaring the window closed. If you automate these checks, make a wrong status, missing body marker or failed connection fail the check explicitly.
Keep the window temporary. Google's crawler documentation explains that server errors slow crawling and persistent failures can affect indexed URLs. A 503 is a truthful response to temporary unavailability, not a guarantee that a long outage has no search consequences.
For the hypothetical deployment, the finish line is observable: callers receive the intended temporary failure during the window and the real application afterward. Rehearse both transitions before you need them.
Rehearse the maintenance window on a Cube
Use a separate, self-managed Linux Cube to stage your application's response, proxy route and recovery checks before changing the service your users depend on.
Creation context: this guide was researched and written with AI assistance, and its conceptual cover was AI-generated. The deployment scenario and configuration are illustrative. No NGINX deployment, customer incident or recovery test was executed for this article.




