Generador de respuestas HTTP mock

Un cuerpo de error bien diseñado

Elegir el código de estado es la mitad del trabajo; la otra mitad es qué devuelves en el cuerpo. Y ahí casi todo el mundo improvisa, con el resultado de que cada endpoint de la misma API devuelve los errores de una forma distinta.

Existe un estándar para esto: el RFC 9457 —antes 7807—, que define un formato común llamado problem details con el tipo de contenido application/problem+json:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://api.ejemplo.com/errores/ruc-invalido",
  "title": "El RUC no es válido",
  "status": 400,
  "detail": "El dígito verificador de 20481234560 no corresponde.",
  "instance": "/clientes/alta/8f3e",
  "errores": [
    { "campo": "ruc", "mensaje": "Dígito verificador incorrecto" }
  ]
}

Los cinco campos tienen un papel claro: type identifica la clase de error de forma estable —es lo que tu cliente debe mirar, no el texto—, title es un resumen legible, status repite el código, detail explica este caso concreto, e instance identifica la ocurrencia para poder buscarla en los registros.

La regla que se deriva: tu cliente nunca debe decidir en función del texto del mensaje. Los textos cambian, se traducen, se corrigen. El type —o un código propio— es lo estable.

El error más caro: devolver 200 con un error dentro

// MAL: el código dice que todo fue bien
HTTP/1.1 200 OK
{ "exito": false, "error": "Usuario no encontrado" }

// BIEN: el código ya lo dice
HTTP/1.1 404 Not Found
{ "type": "...", "title": "Usuario no encontrado", "status": 404 }

Con el primero, todo lo que hay entre tu servidor y tu cliente se equivoca: el reintento automático no reintenta porque cree que funcionó, la caché guarda la respuesta de error, los paneles de monitorización muestran cero errores mientras los usuarios se quejan, y cada cliente tiene que aprender a mirar dentro del cuerpo. Es el antipatrón más extendido en API internas.

401 y 403 no son lo mismo

Confundirlos tiene un efecto muy concreto y muy molesto: si devuelves 401 cuando querías decir 403, la aplicación intentará renovar el token, lo conseguirá, reintentará, volverá a recibir 401… y acabará cerrando la sesión del usuario por un problema de permisos que no tenía nada que ver con su identidad.

Cuando el 401 es porque el token expiró, ayuda mucho añadir la cabecera WWW-Authenticate: Bearer error="invalid_token": así el cliente sabe que debe renovar y no que debe pedir la contraseña otra vez.

El 500 y lo que nunca debe llevar dentro

Un 500 significa que algo se rompió en tu servidor, y el cuerpo debe decir exactamente eso y nada más. Lo que no puede llevar:

• La traza de la excepción. Revela rutas del sistema de archivos, versiones de librerías y estructura interna: es un mapa para quien quiera atacarte.
• Consultas SQL o fragmentos de consulta.
• Datos de otros usuarios que estuvieran en memoria.

Lo correcto es un mensaje genérico más un identificador de incidencia: «Error interno. Referencia: 7f3a9c». Ese identificador va también a tus registros, así que el usuario te lo puede dar y tú encuentras el detalle sin haberlo publicado.

Qué probar con respuestas mock

• Los cinco códigos, uno por uno. Configura tu mock server para devolver cada uno y comprueba qué hace tu interfaz. El 500 y el 401 son los que peor se manejan.
• Un cuerpo vacío. Un 500 sin JSON dentro. Muchos clientes intentan parsear la respuesta y se rompen con un error de sintaxis que oculta el error real.
• HTML donde esperas JSON. Es lo que devuelve un servidor caído o un proxy: una página de error. Si tu cliente no comprueba el tipo de contenido, el mensaje que verá el usuario será incomprensible.
• Una respuesta lenta. Combina el mock con un retardo y comprueba que tu interfaz muestra un indicador de carga y que el tiempo de espera está configurado.
• Un 404 en una ruta que sí existe. Para distinguir «el endpoint no existe» de «el recurso no existe»: son dos cosas y el usuario merece mensajes distintos.