Manejo global de errores en el framework

En las versiones recientes de Laravel, como la 12, el manejo global se configura en bootstrap/app.php con withExceptions. Ahí se decide qué se registra (report), qué clases no se registran nunca (dontReport) y cómo se convierte una excepción en respuesta (render). La cantidad de detalle que se muestra la gobierna además el ajuste de depuración, que en producción tiene que estar apagado. El Top 10 de OWASP recomienda exactamente esta pieza: un manejo centralizado y coherente, con un manejador global como último recurso.

Último recurso es la palabra importante. El manejador global garantiza que nada salga en crudo y que todo quede registrado, pero no conoce el negocio: no sabe si un pedido se retiene, se revierte o se reintenta. Eso se decide donde ocurre la excepción. Y como todo pasa por él, un error en su configuración se repite en toda la aplicación a la vez.

Abre el laboratorio y lee app.php con excepciones-propias.txt al lado. La lista que no se reporta se armó para quitar ruido, y dos de sus clases son errores esperados cuya causa es el cliente. La tercera es otra cosa. Compara con errores-reportados-nov.txt: el proveedor de pagos tuvo dos incidentes ese mes y el conteo de la tienda no lo refleja.

El render de la configuración responde a toda excepción de la API con su clase y su mensaje, y siempre con código 500. El mensaje de una excepción se escribió para quien depura, no para el cliente: en una falla de conexión a la base de datos puede traer el motor, el servidor y la consulta. Y el código fijo en 500 rompe el otro extremo: un error de validación del cliente sale como si fuera del servidor. Lee respuestas-capturadas.txt.

El manejador global solo ve lo que llega hasta él. Un catch que atrapa una excepción genérica y no hace nada con ella la hace desaparecer antes: no se registra, no se alerta y el usuario recibe una respuesta que finge normalidad. El catálogo CWE tiene nombre para las dos partes del problema: capturar una excepción genérica (CWE-396) y detectar un error sin actuar (CWE-390). Lee catch-en-controladores.txt y separa los bloques que capturan algo genérico de los que capturan una excepción concreta y esperada; de los genéricos, descarta los que reportan, registran o vuelven a lanzar.

Los hallazgos de esta sala se corrigen en dos sitios. En la configuración global: las fallas de dependencias se reportan siempre, y la API responde con un formato propio para el cliente, el código de estado que corresponde a cada error y un identificador del incidente, dejando el mensaje interno solo en el registro. En los controladores: cada catch genérico que se traga el error pasa a reportarlo o se reemplaza por una captura de la excepción concreta que se espera.