Begin with the response, then design the page
A polished maintenance page can still send the wrong signal to software. For a temporary period when the service cannot handle a request, MDN documents the 503 Service Unavailable response. Returning a normal success status with an error message in the body describes a different situation. Start by deciding when the temporary response should be active and which routes it affects. Then write the page people will actually see, keeping the essential explanation available without a large script bundle.
Give the reader a useful next action
Say which operation is unavailable, whether the reader should wait or use another published route, and when an update will be available. Do not promise a restoration time merely to make the layout look complete. The Retry-After header can express a delay in seconds or an HTTP date, although client support varies. Its value should reflect an estimate the operator can justify. A made-up countdown is no substitute for an incident owner checking the service.
Test entry and exit together
Prepare two checks: the temporary response is active when intended, and the ordinary page returns after maintenance ends. Include a deep article or application route as well as the home page. Inspect response headers with your usual HTTP tool, then review the visible page at a narrow width. Pay attention to caching so that the temporary response does not remain visible after recovery. Keep the previous configuration available privately in case the switch behaves differently from the rehearsal.
Keep maintenance separate from traffic mitigation
A maintenance page is a way to communicate and control a planned temporary condition. It does not establish that an upstream traffic problem has been resolved. If an investigation points towards the need for DDoS proxy services, KoDDoS describes a remote arrangement that can be discussed separately with the hosting team. Establish the affected routes, covered protocols and origin-access requirements before changing the traffic path. Application maintenance and network protection need their own acceptance checks.
Write down the exit condition
For an illustrative publishing system, the exit condition could be that the ordinary home page, a deep article and an image return correctly and that the publishing task completes. Use the operations that matter to your actual service. Assign someone to remove or update the public notice after those checks pass. Keeping a temporary page live by accident turns a small maintenance window into a new incident. The final step belongs in the runbook, not in somebody’s memory.
Put it into practice
HTTP/1.1 503 Service Unavailable
Content-Type: text/html; charset=utf-8
Retry-After: 300
Cache-Control: no-storeIllustrative response: 300 seconds means five minutes. Use a delay appropriate to the actual operation, configure the response on your own server, and test that normal responses return afterwards.
Sources & further reading
Examples and worksheets on this page are illustrative. Documentation links were checked in November 2026; follow the relevant product’s current instructions.
