Función PHP http_response_code()

Cada respuesta HTTP que envía un servidor lleva un código de estado — un número de tres dígitos que indica al navegador (o al cliente de la API) si la solicitud tuvo éxito, fue redirigida o falló. La función integrada http_response_code() de PHP, añadida en PHP 5.4, te permite leer o establecer ese código con una sola llamada. Es la manera más sencilla y portable de devolver un 404 Not Found, una redirección 301, un 403 Forbidden u cualquier otro estado desde un script PHP.

Este capítulo cubre la sintaxis, cómo obtener o establecer el código actual, los códigos más comunes que usarás, el problema del búfer de salida que confunde a muchos, y cómo se compara http_response_code() con establecer la línea de estado manualmente usando header().

Qué hace http_response_code()

http_response_code() tiene dos modos según si le pasas un argumento:

• Modo establecer — http_response_code(404) establece el código de estado de respuesta en 404.
• Modo obtener — http_response_code() (sin argumento) devuelve el código de estado actual como un entero, o false (en CLI devuelve true/false) si aún no se ha establecido ningún código en un contexto web.

Solo afecta al código de estado en sí. No envía un cuerpo, redirige el navegador ni imprime una página de error — eso sigue siendo tu responsabilidad.

Sintaxis

http_response_code(int $response_code = null): int|bool

Valor de retorno: al establecer, devuelve el código anterior (o 200 si no se había establecido ninguno). Al obtener en un contexto web, devuelve el código actual. Fuera de un servidor web (CLI), devuelve true tras establecer y false al leer sin código establecido.

Establecer un código de estado

El uso más habitual es devolver una respuesta "no encontrado" desde un enrutador o un manejador de páginas inexistentes:

<?php
// Tell the client this page does not exist
http_response_code(404);
echo "Page not found.";

El 404 se escribe en la cabecera de respuesta que se envía antes del cuerpo, por lo que el navegador sabe que la solicitud falló aunque hayas impreso un mensaje.

Un 403 para un recurso bloqueado tiene el mismo aspecto:

<?php
if (!$userIsLoggedIn) {
    http_response_code(403);
    exit("Access denied.");
}

Leer el código de estado actual

Llama a la función sin argumento para saber qué código lleva actualmente la respuesta — útil en funciones de apagado, registro de eventos o middleware:

<?php
http_response_code(404);

// Later in the same request:
$current = http_response_code();
echo $current; // 404

Redirigir con un código de estado

Una redirección necesita dos cosas: el código de estado correcto y una cabecera Location. Usa http_response_code() para el código y header() para el destino:

<?php
// Permanent redirect to the new URL
http_response_code(301);
header("Location: https://www.w3docs.com/new-page");
exit;

Usa 301 para un traslado permanente (los motores de búsqueda actualizan su índice) y 302/307 para uno temporal.

Códigos de estado HTTP más comunes

El problema de las "cabeceras ya enviadas"

Los códigos de estado residen en las cabeceras HTTP, y las cabeceras deben enviarse antes de cualquier salida. Si tu script ya ha enviado HTML, impreso una línea en blanco, o incluso tiene espacios en blanco antes de la etiqueta de apertura <?php, las cabeceras ya se han enviado y http_response_code() no hace nada silenciosamente (PHP también emite una advertencia de "headers already sent").

<?php
echo "Hello";          // body sent → headers are now locked
http_response_code(404); // too late, has no effect

Para comprobar si la salida ya se ha enviado, usa headers_sent():

<?php
if (!headers_sent()) {
    http_response_code(404);
}

Soluciones para las causas más comunes: elimina los espacios en blanco errantes antes de <?php, evita echo/print antes de establecer el código, o habilita el búfer de salida con ob_start() para retener la salida hasta que estés listo.

http_response_code() vs. header()

Antes de PHP 5.4 tenías que construir la línea de estado manualmente con header():

<?php
// The old way — still works, but verbose and you must repeat the protocol/text
header("HTTP/1.1 404 Not Found");

// The modern equivalent
http_response_code(404);

http_response_code() es preferible porque no requiere que escribas directamente la versión HTTP ni el texto del estado, y también puede leer el código actual — algo que una llamada a header() directa no puede hacer. Consulta header() y headers_list() para un control más detallado de las cabeceras de respuesta.

Conclusión

http_response_code() es la forma más limpia de leer o establecer un código de estado HTTP en PHP. Recuerda las tres cosas que importan en la práctica: llámala antes de cualquier salida, elige el código correcto para la situación (404 para recursos no encontrados, 403 para acceso prohibido, 301/302 para redirecciones), y combina las redirecciones con una cabecera Location usando header(). Para profundizar en las herramientas de solicitud/respuesta de PHP, explora las funciones PHP y la función header().

Práctica