How do I make php page return a 503 error (or anything non-200)

How do I make php page return a 503 error (or anything non-200)

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How do I make php page return a 503 error (or anything non-200)

When building a client-server API, the separation between application logic and HTTP protocol handling is often where errors slip through. A common scenario involves a backend service that accepts messages via POST requests and responds with XML payloads. The problem arises when the server encounters an issue, such as invalid arguments or a resource exhaustion event, but the application still sends back a 200 OK status code alongside an error message like <h4>Unknown error!</h4>.

From the perspective of the client application, this is problematic. Many HTTP clients and load balancers rely on specific status codes to determine how to handle the response. A 200 status implies success, which might cause the client to proceed with optimistic processing or cache the result incorrectly. To fix this, you need to understand that PHP generates the status line before it renders any HTML or XML content. You must explicitly instruct the web server to change the status code before echoing your response body.

The most direct way to achieve this in vanilla PHP is by using the http_response_code() function. This function sets the HTTP status code for the current script execution. It must be called before any output is sent to the browser, including whitespace or BOMs. Here is how you can structure your response logic:

<?php
// Assume $error is set because arguments were invalid
$error = true; 

if ($error) {
    http_response_code(503); // Service Unavailable
    // Or 400 for Bad Request, depending on the specific error type
    
    header('Content-Type: application/xml');
    
    echo '<h4>Unknown error!</h4>';
} else {
    http_response_code(200);
    header('Content-Type: application/xml');
    
    echo '<success>Message received</success>';
}
?>

In this example, we are explicitly setting the code to 503 when an error occurs. This tells the client that the server is currently unable to handle the request due to temporary overloading or maintenance. However, you must be careful about what specific status code you choose. A 400 Bad Request is semantically more accurate for invalid arguments because the server refused the request due to malformed syntax in the initial request. A 503 is generally reserved for server-side issues where the server is overwhelmed or down. Choosing the wrong code can mislead monitoring systems and client retry logic.

There is a critical pitfall to watch out for regarding output buffering. If your application starts echoing data or sends headers prematurely, http_response_code() will fail to change the status line. This often happens if there are blank lines at the top of the file or if a library automatically flushes buffers. To ensure this works reliably, you might need to disable output buffering with ob_start() before setting any codes, though modern PHP versions often handle this gracefully if no prior output has occurred.

If you are already using a framework like Laravel, the approach shifts slightly because the framework manages the response lifecycle. In such environments, you would typically return a Response object or throw an exception that gets converted to a specific status code by the error handler. For instance, throwing an HttpException with a 503 code allows the framework's middleware to intercept the error and send the correct headers before rendering any view.

Ultimately, the goal is to maintain a strict contract with your API consumers. Returning a non-200 status code provides immediate signal to the client that something went wrong, allowing them to implement appropriate retry mechanisms or fail gracefully without parsing the response body for error details.

Our network