Maintenance Mode: Correct Use of 503 and Retry-After
Direct Answer
The requested URL should normally remain the requested URL while temporarily unavailable; avoid redirecting every request to /maintenance. Return 503, keep the error page lightweight, and make sure CDN or application caches do not accidentally persist the temporary response after recovery. For ordinary users this means old bookmarks and links should resolve reliably to the correct new state. For developers it means every participating layer needs a measurable expected-versus-observed test. A maintenance page is an unavailable state. Returning 200 OK with maintenance text creates a soft-error signal; keep the requested URL and return 503 rather than redirecting the whole site to one maintenance URL. Define the expected public result before release and verify the same result after release instead of trusting configuration or a browser screenshot.
Documentation
What this check actually means
The requested URL should normally remain the requested URL while temporarily unavailable; avoid redirecting every request to /maintenance. Return 503, keep the error page lightweight, and make sure CDN or application caches do not accidentally persist the temporary response after recovery.
Expected behavior and decision boundary
Expected state: The requested URL should normally remain the requested URL while temporarily unavailable; avoid redirecting every request to /maintenance. Return 503, keep the error page lightweight, and make sure CDN or application caches do not accidentally persist the temporary response after recovery. Define an expected status, expected destination, and owner for every URL/host class before launch. PASS means observed HTTP/DNS/DOM behavior matches that definition without unexplained intermediate states.
Diagnosis: evidence to capture
Record the test as data so release and SEO teams see the same state:
url,expected_status,actual_status,expected_target,actual_target,canonical,robots,owner
https://old.example/a,301,301,https://new.example/a,https://new.example/a,https://new.example/a,index,platform
For host or infrastructure changes, also store DNS answers, TLS/SNI result, CDN cache status, and timestamps. A screenshot alone cannot prove an HTTP status, redirect chain, or resolver state.
Technical implementation
The requested URL should normally remain the requested URL while temporarily unavailable; avoid redirecting every request to /maintenance. Return 503, keep the error page lightweight, and make sure CDN or application caches do not accidentally persist the temporary response after recovery.
HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Type: text/html; charset=UTF-8
Capture at least one representative URL per template/path class and store expected versus observed HTTP status. For DNS/CDN work also record resolver answers, certificate/SNI, host routing, and cache status. For redirects, test the first hop separately from the final destination.
Common root causes
Common causes are incomplete URL inventories, changing domain/CMS/design at the same time, untested edge rules, old absolute URLs embedded in templates, staging/production configuration drift, and no explicit rollback boundary. When something fails, first locate the layer: DNS/TLS, web server/CDN, application routing, CMS/template, or page-level metadata.
Edge cases and false positives
Not every difference is a defect: an intentional 404/410 can be correct, a temporary 302 may be right for testing, and DNS answers can differ while TTLs expire. Define expected behavior per URL class before auto-fixing deviations. For login/API/non-GET endpoints, review redirect semantics separately.
Verification after the fix
| Check | PASS | FAIL | | --- | --- | --- | | Output | expected rule is visible in final HTML/HTTP/DOM | backend field looks correct but final output does not | | Scope | representative URLs from every affected template tested | only one example URL tested | | Source | shared root cause/owner is documented | manual per-page edits without root cause | | Regression | adjacent canonical/robots/accessibility/link rules still pass | fix creates a new defect in the same component | | Evidence | before/after values and test time are stored | only visual impression or screenshot |
Ownership and handoff
Content/SEO owner: defines the expected page purpose and whether the condition actually requires a change.
Developer/platform: fixes the shared template, routing, header, or component source.
QA: tests representative edge states and re-crawls/re-requests after deployment.
Release owner: records time, scope, and rollback point so monitoring signals can be tied to a specific change.
Acceptance criteria
PASS when the final technical state is reproducible on representative URLs, the shared root cause is fixed, intentional exceptions are documented, and a re-crawl/re-request shows no new regression in canonicalization, robots directives, accessibility, links, or rendering.
Worked operational example: defect → fix → proof
Symptom: the audit reports “Maintenance Mode: Correct Use of 503 and Retry-After” on multiple URLs.
Root cause: the repeated output originates in a template, component, CMS fallback, or infrastructure layer.
Fix: change that shared source instead of patching individual pages, and keep the change as small as possible.
Proof: store at least one before/after URL per template, the final HTTP/HTML/DOM output, and the re-crawl result. If an intentional exception remains different, document it so a future audit does not treat it as an unresolved defect.
For production systems, also include a regression sample: same locale, mobile/desktop when relevant, missing-data state, and one URL that was already correct. This proves whether the change stabilizes the generator rather than only the reported example.
Questions & Answers
Should a migration and redesign happen at the same time?
Prefer separating them when practical. Fewer simultaneous changes make root-cause analysis, rollback, and search fluctuations much easier to interpret.
How should redirects be tested?
First request without following redirects and verify the initial status and Location; then inspect the full chain and final 200 destination. A successful end page does not prove the path is clean.
What should be monitored first after launch?
HTTP errors, robots/noindex, redirect targets, canonicals, sitemap output, and server/CDN failures first; indexing and query trends require a longer window.
When is rollback better than a hotfix?
When the defect is broad, the cause is uncertain, or routing/indexability is severely damaged and a known-compatible rollback is available.
Practical Check
- Define the affected URL/template class and write the expected behavior before changing anything.
- Capture raw HTTP/HTML; when client-side code changes output, also inspect the rendered DOM.
- Validate the redirect/status matrix against final destinations; do not start with a follow-redirect-only test.
- Trace the defect to its shared layer: DNS/CDN, routing, template, component, CMS field, or editorial content.
- Implement the smallest systemic fix and preserve a rollback point first.
- Test positive cases, missing/empty data, and at least one relevant edge state.
- Re-crawl or re-request every affected template/URL class and store before/after evidence.
- PASS: expected behavior is reproducible, no adjacent SEO/accessibility rule regresses, and the fix does not require manual per-page workarounds.