Read more

Be careful to use correct HTTP status codes for maintenance pages

Henning Koch
September 15, 2017Software engineer at makandra GmbH

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.

Illustration web development

Do you need DevOps-experts?

Your development team has a full backlog? No time for infrastructure architecture? Our DevOps team is ready to support you!

  • We build reliable cloud solutions with Infrastructure as code
  • We are experts in security, Linux and databases
  • We support your dev team to perform
Read more Show archive.org snapshot

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.

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 /maintenance will 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.

Posted by Henning Koch to makandra dev (2017-09-15 12:25)