PHP: Send a 503 Service Temporarily Unavailable header.

In this tutorial, we will show you how to return a “503 Service Temporarily Unavailable” status code using PHP.

This header is useful if you are carrying out maintenance. You can also use it if a technical issue is temporarily preventing your app from working correctly.

By sending a 503 HTTP response code, we are letting the client know that something is “wrong” at the moment and that they should retry at a later stage. It also helps to prevent search engines from indexing broken web apps, etc.

Using PHP’s header function to respond with a 503 HTTP status code.

In this example, we will use PHP’s header function to respond with a 503 HTTP status code:

//Using PHP's header function to send a 503
//Service Temporarily Unavailable status code to the client.
header($_SERVER["SERVER_PROTOCOL"]." 503 Service Temporarily Unavailable", true, 503);

//The number of seconds that the client should
//wait before retrying.
$retryAfterSeconds = 240;

//Send a Retry-After header to the client.
header('Retry-After: ' . $retryAfterSeconds);

//Send a message to the browser so that the user
//knows what is going on.
echo '<h1>503 Service Temporarily Unavailable</h1>';
echo '<p>Our site is currently under maintenance.</p>';

//Kill the PHP script.
exit;

In the PHP code above:

  1. We sent a “503 Service Temporarily Unavailable” status code to the client using PHP’s header function. Note that we used $_SERVER[“SERVER_PROTOCOL”] because we cannot assume that the client will be using HTTP/1.1. For all we know, they could be using HTTP/1.0.
  2. We sent a Retry-After header to the client. This header tells the client how many seconds they should wait before trying again. Note that the client can simply ignore this header if they want to. Thankfully, bots and crawlers such as Googlebot will honor it.
  3. Finally, we printed a basic “under maintenance” message and exited the PHP script.

If you do not provide a custom message, browsers such as Chrome will display the following message:

503 Chrome

Personally, I think that the default 503 error message doesn’t provide enough information to the user.

Using the http_response_code function to return a 503 error.

If you are using PHP version 5.4.0 or above, then you can send a 503 response code using the http_response_code function:

//Use PHP's http_response_code function to send a 503
//Service Temporarily Unavailable status code to the client.
http_response_code(503);

//Seconds until the client should retry.
$retryAfterSeconds = 240;

//Retry-After header.
header('Retry-After: ' . $retryAfterSeconds);

//Custom message.
echo '<h1>503 Service Temporarily Unavailable</h1>';
echo '<p>Our site is currently under maintenance.</p>';

//Exit the script.
exit;

The code above works the exact same way as the PHP code in our first example.

The only difference is that you don’t have to manually write out the full header details.

For other useful HTTP response codes, see: