Tema 8 · Manejo de Errores

8. Personalización de Respuestas de Error 422 y Manejador de Excepciones

Garantiza que cualquier excepción (ValidationException, ModelNotFoundException) devuelva JSON uniforme respetando la cabecera Accept: application/json.

La Cabecera Vital: Accept: application/json

Muchos desarrolladores descubren que cuando un Form Request falla, Laravel intenta hacer una redirección HTTP 302 con sesiones flash hacia la página anterior. Esto ocurre cuando el cliente que consume la API olvida enviar la cabecera HTTP:

Accept: application/json

En Laravel moderno podemos forzar a nivel de middleware que todas las peticiones que ingresen por routes/api.php sean tratadas estrictamente como peticiones JSON, eliminando redirecciones 302 no deseadas.

Personalización Global de Excepciones en bootstrap/app.php

En Laravel 11 y 12, el manejo de excepciones se configura limpiamente en el closure withExceptions() de bootstrap/app.php:

  • $exceptions->shouldRenderJsonWhen(...): Fuerza respuestas JSON para cualquier ruta con prefijo api/*.
  • $exceptions->render(function (AuthenticationException $e, $request) { ... }): Personaliza errores 401.

⚡ Forzar Respuestas JSON y Personalizar Excepciones en bootstrap/app.php

Configuración de excepciones en Laravel moderno para evitar fugas y redirecciones:

configuracion-excepciones.php
Solo lectura
<?php

use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Illuminate\Auth\AuthenticationException;

// Dentro de bootstrap/app.php ->withExceptions(function (Exceptions $exceptions) {

    // 1. Forzar que cualquier ruta /api/* responda SIEMPRE en JSON
    $exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
        return $request->is('api/*') || $request->expectsJson();
    });

    // 2. Personalizar respuestas de 404 Not Found en la API
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'status'  => 'error',
                'code'    => 404,
                'message' => 'El recurso solicitado o endpoint no existe.',
            ], 404);
        }
    });

    // 3. Personalizar respuestas de 401 Unauthorized sin redirección a /login
    $exceptions->render(function (AuthenticationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'status'  => 'error',
                'code'    => 401,
                'message' => 'No autenticado. Se requiere un Bearer Token válido.',
            ], 401);
        }
    });

// });
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué cabecera HTTP debe enviar el cliente para indicarle a Laravel que espera recibir una respuesta en formato JSON ante cualquier fallo?
🦉
¿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 Laravel, Resources & Sanctum 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.