Los mensajes genéricos son cómodos para el usuario, pero terribles para diagnosticar. En una aplicación PHP, una operación de alta terminaba con «El servidor devolvió una respuesta no válida». No indicaba si había expirado la sesión, si fallaba la base de datos o si el endpoint no existía.
Qué significa realmente una respuesta no válida
El JavaScript esperaba recibir JSON. Si el servidor devuelve una página de error, un warning, texto antes de la cabecera o incluso una respuesta vacía, el parser falla. La interfaz solo sabe que no ha recibido el formato acordado.
En este caso inspeccioné primero el código que interpretaba la respuesta y después el PHP responsable del alta. Encontré una llamada a un método nuevo fuera del bloque que transformaba las excepciones en JSON. Una versión antigua de la clase provocaba un fatal y PHP generaba HTML.
Por qué el mensaje ocultaba un problema mayor
La operación ya había escrito parte de los datos antes del fatal. Por tanto, no era suficiente con mejorar el texto del error. Había que hacer el flujo compatible, controlar dónde se producía cada efecto y evitar que el usuario repitiera el alta.
Las mejoras aplicadas
- Compatibilidad temporal entre versiones nuevas y antiguas de la clase.
- Captura de errores antes de que PHP pudiera devolver HTML sin estructurar.
- Respuesta JSON consistente, incluso en errores inesperados.
- Visualización del código HTTP y de un detalle seguro para soporte.
- Comprobación previa de duplicados antes de repetir el alta.
Cómo debería responder un endpoint
Una API interna no necesita revelar rutas o credenciales, pero sí debe comunicar un código estable, un mensaje comprensible y un identificador de seguimiento. Por ejemplo: operación no autorizada, validación fallida, conflicto por duplicado o error interno.
En el servidor, el log puede conservar el detalle técnico completo. En el navegador, basta con información accionable. Esta separación mejora tanto la seguridad como el tiempo de resolución.
Mi regla para los errores AJAX
No doy por hecho que el problema está en JavaScript. Primero compruebo el estado HTTP, el tipo de contenido y los primeros caracteres de la respuesta. Si aparece HTML donde esperaba JSON, voy directamente al log PHP y reviso en qué punto se envió la salida.