Hace poco me encontré con uno de esos errores que engañan porque la pantalla cuenta solo una parte de la historia. Al crear un cliente desde una aplicación de gestión, el usuario recibía el mensaje «El servidor devolvió una respuesta no válida». Parecía que el alta había fallado por completo. En realidad, el cliente ya se había guardado en la base de datos principal y el proceso se rompía unos milisegundos después, justo antes de sincronizarlo con WordPress.
Por confidencialidad omito el nombre del proyecto y cualquier dato personal. Lo interesante del caso es el método: antes de repetir una operación debemos descubrir hasta dónde llegó realmente.
El riesgo de repetir un alta que parece fallida
La primera reacción suele ser pulsar otra vez. En este caso habría creado duplicados o dejado usuarios con estados diferentes en dos sistemas. Revisé primero la tabla de clientes y confirmé que la escritura principal sí se había completado. El error estaba en la fase posterior.
La aplicación esperaba una respuesta JSON, pero PHP estaba produciendo un error fatal en HTML. El navegador no podía interpretarlo y lo resumía con un mensaje genérico. Esa capa de presentación ocultaba la causa real.
La causa: un despliegue parcial
Un archivo nuevo llamaba a un método que todavía no existía en una clase antigua instalada en el servidor. Era una versión desalineada: parte del código se había actualizado y parte no. La creación del cliente terminaba correctamente, pero al intentar consultar el identificador del sitio WordPress se detenía la ejecución.
Preparé una alternativa compatible con ambas versiones, moví el tratamiento de errores a un punto donde siempre pudiera devolver JSON y mejoré el mensaje del navegador para incluir el código HTTP y una explicación útil.
Cómo comprobé que la solución era segura
- Verifiqué que los clientes de intentos anteriores ya existían antes de repetirlos.
- Validé la sintaxis PHP y JavaScript.
- Ejecuté 16 pruebas con 64 comprobaciones sobre el flujo de clientes.
- Separé claramente «guardado en la aplicación» de «sincronizado con WordPress».
- Documenté qué archivos debían desplegarse juntos.
La lección que aplico desde entonces
Cuando una operación atraviesa varios sistemas, un único mensaje de éxito o error es insuficiente. Cada etapa importante debe poder auditarse: validación, escritura principal, llamada externa, respuesta y resultado final. También conviene que los despliegues sean atómicos o, como mínimo, compatibles durante la transición.
Si una aplicación guarda datos pero WordPress no los recibe, no empezaría tocando el endpoint a ciegas. Primero comprobaría qué sistema tiene ya la información, qué identificador está utilizando y en qué punto exacto se interrumpe el flujo.