Tema 3 · Códigos de Estado

3. Códigos de Estado HTTP Esenciales: 200, 201, 204, 400, 401, 403, 404, 422 y 500

Comunica con precisión el resultado de cada operación utilizando los códigos de estado estándar de la IETF en lugar de devolver siempre 200 con un mensaje de error.

El Antipatrón del "HTTP 200 OK con Error"

Uno de los errores más comunes de desarrolladores inexpertos es devolver una cabecera HTTP 200 OK acompañada de un cuerpo JSON como {"error": "Usuario no encontrado"}. Esto destruye la semántica del protocolo HTTP: librerías cliente como Axios o fetch() asumen que la petición fue exitosa y no activan sus bloques de captura de errores (catch).

Las Cinco Familias de Códigos HTTP en APIs REST

Código Nombre Oficial Cuándo Emitirlo en tu API
200 OK Petición Exitosa Consultas GET con datos, actualizaciones PUT/PATCH exitosas.
201 Created Recurso Creado Respuesta estándar a un POST exitoso. Suele acompañarse del ID generado o el recurso recién insertado.
204 No Content Sin Contenido Operación exitosa pero la respuesta no lleva cuerpo (ideal tras un DELETE o preflight OPTIONS).
400 Bad Request Petición Inválida Sintaxis JSON corrupta o malformada que el servidor no puede ni siquiera parsear.
401 Unauthorized No Autenticado Falta el token de autenticación (JWT) o el token expiró / es inválido. "No sé quién eres".
403 Forbidden Prohibido / Sin Permiso El usuario está autenticado válidamente, pero no tiene permisos para ese recurso. "Sé quién eres, pero no tienes acceso".
404 Not Found No Encontrado El endpoint no existe o el registro con el ID solicitado no fue hallado en la base de datos.
422 Unprocessable Entidad Improcesable El JSON es sintácticamente válido pero falló la validación de negocio (ej: email no válido, contraseña muy corta).
500 Internal Error Error del Servidor Excepción no controlada en PHP, fallo de conexión a base de datos o error fatal del servidor.

⚡ Helper para Respuestas HTTP Estandarizadas en PHP Puro

Función helper reutilizable para emitir códigos de estado y JSON estructurado:

helper-respuestas.php
Solo lectura
<?php
declare(strict_types=1);

/**
 * Emite una respuesta JSON con código de estado HTTP estándar.
 */
function responderJson(int $codigoHttp, array $datos): void
{
    // 1. Establecer el código de estado en la cabecera HTTP real
    http_response_code($codigoHttp);

    // 2. Definir Content-Type
    header('Content-Type: application/json; charset=utf-8');

    // 3. Serializar y enviar
    echo json_encode($datos, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
    exit;
}

// Ejemplo: Emisión de error 404
// responderJson(404, [
//     'status'  => 'error',
//     'code'    => 404,
//     'message' => 'Producto con ID 99 no encontrado en el catálogo'
// ]);

// Ejemplo: Emisión de éxito 201 Created
responderJson(201, [
    'status'  => 'success',
    'code'    => 201,
    'message' => 'Usuario registrado exitosamente',
    'data'    => [
        'id'     => 45,
        'nombre' => 'Juan Sebastián Amador',
        'email'  => '[email protected]'
    ]
]);
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Cuál es la diferencia exacta entre el código HTTP 401 (Unauthorized) y el código 403 (Forbidden)?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar APIs RESTful con PHP Puro, JSON & JWT y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.