When your public-facing application has a longer downtime for server maintenance or long migrations, it's nice to setup a maintenance page to inform your users.
When delivering the maintenance page, be very careful to send the correct HTTP status code. Sending the wrong status code might get you kicked out of Google, or undo years of SEO work.
Popular footguns
Here are some ways to shoot yourself in the foot during maintenance:
- If all your routes send a "200 OK" with a HTML body "We're back soon", Google will index "We're back soon" as the text for all your URLs.
- If all your routes send a "404 Not Found", Google will remove all your URLs from its index.
- If all your routes send a "301 Moved Permanently" with a redirect to
/maintenance, that/maintenancewill be the only path left in the Google index. Also browsers will cache the redirect forever.
Appropriate status code for maintenance pages
The best HTTP status code for your maintenance page is "503 Service Unavailable":
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.
If you absolutely need to implement your maintenance page as a redirect to /maintenance (discouraged), make sure to use 302 Found to signal a temporary redirect.
If you want to be a super cool HTTP citizen you might also send:
Retry-After: 3600
This signals agents to retry after one hour.
