Maintenance States

Last updated:

Practical patterns for planned downtime and outages with honest messaging and recovery.

01 — Foundation

Maintenance is a planned state — not a broken site

When systems are down, users need honesty, timing, and alternatives.

Maintenance and outage pages appear during deploys, incidents, and emergencies. A generic 404 or blank page erodes trust. Clear copy, realistic time windows, and links to status information reduce support load and panic.

02 — Message

What to communicate

Say what is unavailable, why, and when to check back.

  • plain headline — “Scheduled maintenance” or “We are fixing an issue”
  • time window in the user’s timezone when known — avoid false precision
  • link to status page, RSS, or social channel for updates
  • contact or support path for urgent business-critical users if applicable

03 — HTTP

Status codes and caching

Machines and monitors read headers — users read the page.

  • use appropriate codes — 503 with Retry-After for temporary maintenance where possible
  • do not cache outage pages aggressively at CDN edge during active incidents
  • distinguish planned maintenance from unexpected outage copy 
<main>
    <h1>Scheduled maintenance</h1>
    <p>We will be back by 04:00 GMT. <a href="https://status.example.com/">Status updates</a></p>
</main>

04 — In-app

Banners vs full-page maintenance

Partial degradation may need a banner; total outage needs a dedicated view.

  • partial features down — use Announcement Banners with clear scope
  • read-only mode during migrations — explain what still works
  • avoid login loops that fail silently — show maintenance before auth churn

05 — Review

Before you approve

A short checklist for maintenance states in code review.

  • message is honest and specific; status link is provided
  • HTTP semantics and caching support recovery
  • page is accessible, lightweight, and readable on mobile