HTTP 503 Service Unavailable Handling

Learn what is and how to fix the HyperText Transfer Protocol (HTTP) 503 Service Unavailable server error response code fast & easy

HTTP 503 Service Unavailable Handling

The HyperText Transfer Protocol (HTTP) 503 Service Unavailable server error response code indicates that the server is not ready to handle the request. Common causes are a server that is down for maintenance or overloaded. See now how to deal with it and fix the 503 Service Unavailable error.

Sometimes, your site will need some downtime, so you can fix things or update plugins. Most of the time, this tends to be a relatively short period in which Google will likely not attempt to crawl your website. However, if you need more time to fix things, chances are much higher that GoogleBot might come for a visit and be confronted with a website that’s down. So how do we prevent Google from drinking your website?

HTTP 503 Service Unavailable Handling
HTTP 503 Service Unavailable Handling

HTTP status codes, and you

For those not familiar with HTTP status codes, here’s a summary of the ones that apply to you when dealing with site maintenance:

  • 200 OK. This status code dictates that the server was successful in returning a response.
  • 301 Moved permanently. This tells the browser that this page is no longer valid and will redirect to the correct page.
  • 302 / 307 Moved temporarily. There’s some history behind these two HTTP status codes, but what this dictates to the browser is that you’ll temporarily redirect the browser to a different page and that the current URL will eventually return to its former state.
  • 404 Not Found. This status code means that the page you were trying to navigate to couldn’t be found.
  • 410 Content Deleted. Use this if you delete your content, and there will be no replacement.
  • 503 Service unavailable. This is the one you want to be returning to Google when you’re dealing with site maintenance. It tells Google you are working on this page or something else went wrong. Google knows that when this status code is returned, check the page again later. This is what we’ll be discussing a bit more.

Please note that Google will consider pages returning the 200 HTTP status code, despite an error (or very little content) on the page, as a “soft 404” in Google Search Console.

How to Fix 503 Errors in WordPress?

Because you’re often unsure what’s causing a 503 error in a particular situation, you need to be methodical in troubleshooting. The following six sections each cover potential solutions addressing various possible causes.

After each step, take a moment to go back to your website and see if the 503 error goes away. If so, you have successfully resolved the issue. If not, continue to the next step in the process.

Temporarily disable your WordPress plugins

One of the most common causes of 503 errors in WordPress is plugin compatibility issues. To determine if this is the case, you need to disable all plugins for your site. Since a 503 error prevents you from accessing the WordPress admin, you will need to use an FTP client for this step. If you don’t have it set up, we recommend FileZilla. No needs to worry, only deleting the plugin will not delete it’s data.

Deactivate your WordPress theme to fix HTTP 503 service unavailable error

Now that you’ve ruled out plugins causing the 503 error, it’s time to do the same for your active theme. In fact, your theme may also cause compatibility issues.

Unfortunately, the process doesn’t work as above. If you just rename the theme folder, WordPress will not revert to the default theme, and you will end up with errors like “Theme directory ‘theme-name’ does not exist”. Alternatively, if you try to rename the entire theme directory folder, you will end up with “Error: Themes directory is empty or does not exist. Please check your installation.”

Temporarily disable your Content Delivery Network (CDN)

Sometimes 503 errors don’t appear because of a problem with your website, but because of your content delivery network (CDN). If you’re using a CDN, you can quickly determine if this is the case by temporarily disabling it.

Every CDN should include a feature that allows you to suspend its service. If you use CloudFlare, you can disable Kinsta CDN by navigating to CDN → “Disable CDN” in the Dashboard: the process you need to follow may vary depending on the CDN you are using. Cloudflare is known sometimes to cause 503 errors. If you can’t find the option to suspend service, check your service’s knowledge base, which usually has detailed instructions.

If you’re not using a CDN, or find that pausing your service doesn’t help your problem, there are a few other fixes you can try. Remember to reactivate your CDN before continuing.

Restricting the WordPress Heartbeat API to fix HTTP 503 service unavailable error

WordPress Heartbeat is an API built into WordPress that uses the platform to auto-save content to show you plugin notifications, let you know when someone else is working on a post you’re trying to access, and more.

Just like a normal heartbeat, the API works at a high frequency in the background so that it doesn’t miss anything. As you can imagine, this API consumes server resources. Usually, this is not a problem, but in some cases it can cause a 503 error if your server cannot handle the load.

Telling Google you’re busy

If Google runs into a 404 while crawling your site, it’ll usually toss out that page from the search results until it returns the next time to verify the page is back. However, if Google repeatedly runs into a 404 on that specific page, it’ll eventually postpone re-crawling, which means more time will pass before the runner returns in the search results.

To overcome this potential longer loss of rankings, you need to return a 503 status code whenever working on a particular page. The original definition of the 503 Service Unavailable status code, according to this RFC, is:

The server is currently unable to handle the request due to temporary overloading or maintenance. The implication is that this temporary condition 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.

What this means is that returning an HTTP 503 Service Unavailable in combination with a Retry-After header, will tell Google how many minutes to wait before coming back. This does not mean Google will crawl again in exactly X minutes, but it’ll ensure Google doesn’t come back to take a look anytime before.

If you want to implement the header, there are a few options you can choose from.

Using the WordPress defaults to fix HTTP 503 service unavailable error

By default, WordPress already returns a 503 when updating plugins or WordPress core. WordPress allows you to override the default maintenance page by adding a maintenance.php to your wp-content/directory. Please note that you’ll be responsible for adequately returning the error headers. Plan on doing database maintenance? You’ll have to take care of that as well. Add a db-error.php file to your andwp-content/ make sure that you also correctly return an error header here as well.

If you’re looking to add something fancier to your WordPress website, check out WP Maintenance Mode. This plugin also adds many extra features besides what we mentioned in the previous section.

If you’re just writing your code and want a solution that’s easy to implement, you can add the following snippet to your codebase and call it in the code that determines if you’re in maintenance mode:


function set_503_header() {
    $protocol = 'HTTP/1.0';

    if ( $_SERVER['SERVER_PROTOCOL'] === 'HTTP/1.1' ) {
        $protocol = 'HTTP/1.1';
    }

    header( $protocol . '503 Service Unavailable', true, 503 );
    header( 'Retry-After: 3600' );
}

Note that the 3600 In the code, the snippet dictates the delay time in seconds. That means the above sample will tell GoogleBot to return after an hour. It’s also possible to add a specific date and time in Retry-After, but you need to be careful with what you add here, as adding a faulty date might result in unexpected results.

Pro-tips To Fix and Solve 503 Service Unavailable

Most of the time, 503 unavailable service errors are caused by maintenance work or traffic congestion. If not, here are some other tips to help you resolve what might be causing this error.

Restart the server to fix HTTP 503 service unavailable error

A bottleneck in your application’s server chain may be causing the 503 error. One of the easiest solutions is to restart the web server hosting the application. If your application is spread across multiple servers, ensure they are all appropriately restarted to bring the system back online as usual.

Server connection problem

A 503 error might indicate that a server somewhere in the chain is down or unreachable. Most modern applications do not reside on a single server. Instead, applications are distributed across multiple systems or rely on third-party services to run. If one of the servers fails, you may get a 503 error that appears to be from your application.

Incorrect firewall configuration

A firewall is a basic security device that monitors network traffic and acts as a gatekeeper. It helps determine which traffic is safe and which may be malicious. In most cases, firewalls block potentially malicious traffic (and can log it for use by network administrators).

However, a firewall configured in the network may prevent critical traffic from passing through. This is especially true for applications that rely on content delivery networks (CDNs).

These CDNs act as a third-party host for “heavy” content such as images or videos on behalf of your application, allowing your application to maintain its speed and efficiency. However, automated firewall services sometimes run false positives and mistake perfectly safe and valid content from CDNs as malicious. In this case, the firewall closes the content stream, resulting in a 503 error.

Caching to fix 503 service unavailable error

There are a few things you need to take into consideration when working with maintenance pages and returning 503 status codes. If you actively use caching, you might run into a situation where the cache isn’t correctly passing on the 503 status, so please make sure you test this properly before actively using this on the live version of your website.

Robots.txt

Did you know it’s also possible to return a 503 status code for your robots.txt? In this article, Pierre Far from Google explains that Google will halt crawling your website if you return a 503 status code on your robots.txt file. The most significant advantage of this is less server load during maintenance periods.

WordPress theme features

Some great WordPress themes like Visualmo’s come with templates ready to use for your coming soon and maintenance pages.  Check the video below for more info.

Handle your maintenance well!

As we have seen, you can avoid losing rankings by adding a 503 when you’re doing site maintenance to let Google know it can come back to crawl your site later. There are several ways to do this. Pick what works best for you, and you’ll have a well-maintained site with no danger of losing rankings. Good luck!