CF GarageWhy a raw 503 hurts more than the downtime itself
Search engines that receive bare 5xx pages during a planned migration downgrade crawl frequency and, for long windows, start dropping pages from results. Users who see a browser error page assume the business closed. Both losses are avoidable: the edge can answer in your place with a controlled page, a clear message and the correct HTTP semantics.
Setting up a maintenance page step by step
Step 1: define the open scope. Decide what must keep working during maintenance: health-check endpoints, payment webhooks, an API version, your own office IPs. A maintenance page that blocks a Stripe webhook costs more than the downtime it hides.
Step 2: deploy a Worker on the zone. The cleanest implementation is a tiny Worker on a route (example.com/*) that intercepts requests during the window, serves your branded HTML with status 503 and a Retry-After header, and lets listed exceptions through to the origin. A minimal logic sketch:
const OPEN = ["/api/health", "/webhooks/"];
if (!OPEN.some(p => url.pathname.startsWith(p)) && MAINTENANCE_ON) {
return new Response(maintenanceHTML, {
status: 503,
headers: { "content-type": "text/html", "retry-after": "3600" }
});
}
return fetch(request);Step 3: control it with a switch. Bind the toggle to a KV namespace, an environment variable or a simple marker: you want the page deployable in seconds and removable in seconds, without redeploying code.
Step 4: test the semantics. Verify with curl that normal pages return 503, open paths return 200, and crawlers see the Retry-After header. A maintenance page served with status 200 gets indexed as the page of record; a 503 with Retry-After is understood as temporary and retried.
Step 5: layer Always Online for real outages. For unplanned downtime, Caching > Origin Error Pages includes an Always Online option that serves Cloudflare's stored copies of your pages while the origin is unreachable. It is a safety net for content pages, not for transactions: forms and checkouts cannot work against a snapshot, so keep the banner honest about what is and is not available.
Common mistakes during maintenance windows
- Serving the page with status 200. The classic SEO accident: Google indexes the maintenance message as your homepage. Status codes are the message.
- Blocking payment webhooks. Payment gateways retry for a limited window; a blocked webhook becomes a lost order or a disputed subscription. Always exempt webhook routes.
- Forgetting the cache. If your HTML is cached at the edge, the Worker may never fire for cached paths. Either bypass cache for the maintenance route or purge before the window.
- Using a global security mode as a maintenance tool. Challenge toggles were never designed for planned maintenance and add confusion for real users.
- No end condition. A page that stays up for days because nobody owns the switch converts a maintenance into an outage. Set the end time and an owner before starting.
Frequently asked questions
Does Always Online work on a Free plan?
The Always Online feature is available on all plans, including Free. Its coverage depends on what Cloudflare has been able to cache from your site; static-heavy sites benefit most. Workers, used for the controlled maintenance page, are also available on Free within generous limits.
What status code should a maintenance page return?
503 with a Retry-After header, for both humans and crawlers. Google explicitly documents 503 as the correct signal for temporary unavailability and will retry without demoting your pages, provided the window stays reasonable.
Can I keep one language or one path online during maintenance?
Yes, that is exactly what the open-scope list in the Worker does: exempt specific paths, hostnames or IP ranges while everything else gets the maintenance page. Define this list before the window, not during the incident.
How long can a maintenance window last before SEO damage?
Short windows (hours, up to a day) with proper 503 and Retry-After are handled gracefully. Multi-day outages progressively lose pages; if the operation will take days, keep key content available rather than serving one page site-wide.