Respuestas de error útiles sin revelar internos

Para las API existe un formato estándar de error: el detalle de problema para HTTP, publicado por la IETF como RFC 9457, que reemplazó al RFC 7807. Es un objeto JSON con tipo de contenido application/problem+json y unos pocos miembros: type identifica la clase de problema, title lo resume de forma estable, status repite el código HTTP, detail explica esta ocurrencia concreta y instance identifica esta ocurrencia. El propio estándar pide que detail ayude al cliente a corregir el problema, no a depurar el servidor, y advierte contra exponer trazas o detalles de la implementación.

La pieza que hace útil el error sin hacerlo peligroso es el identificador del incidente: el cliente lo recibe en instance, el registro lo guarda junto a la excepción completa, y soporte une los dos sin que el cliente vea nada interno.

Abre el laboratorio y lee respuestas-api.txt. Algunas capturas siguen el contrato; otras devuelven tal cual el mensaje de la librería que falló. El de la base de datos es el más generoso: dice qué restricción se violó y en qué tabla vive, y con eso cualquiera empieza a dibujar el modelo de datos de la tienda.

La captura del pago fallido es el ejemplo que el resto de la API debería seguir: el cliente sabe que no se le cobró, sabe qué hacer y tiene un código para soporte, y no ve nada de cómo está construida la tienda. Comprueba que el diseño funciona del otro lado: con el identificador de esa respuesta, busca en registro-aplicacion.txt qué pasó de verdad.

No todo lo que sobra en un error es un nombre de servidor. Dos respuestas distintas para dos situaciones que el cliente no debería poder separar también filtran información: quien prueba códigos al azar aprende cuáles existen. El punto 5 del contrato de Siemprevida lo prevé, y dos capturas del mismo servicio no lo cumplen.

Para el informe hace falta el alcance: cuántas de las ocho respuestas no cumplen el punto 3 del contrato. Revisa cada captura y marca las que entregan al cliente algo de la construcción interna de la tienda: una consulta o un mensaje del motor de base de datos, una ruta de archivo, un nombre de servidor o el mensaje crudo de una librería.