Manejo de errores en APIs REST (mensajes en JSON, estandarización)

1 Introducción

En cualquier API REST, los errores son inevitables:

  • El cliente puede enviar datos mal formados.
  • Puede intentar acceder a un recurso que no existe.
  • El servidor puede fallar por problemas internos.

👉 Lo importante no es solo detectar los errores, sino comunicarlos de manera clara, consistente y útil al cliente.

2 Principios del manejo de errores en APIs

  • Usar siempre códigos HTTP correctos que indiquen el tipo de error.
  • Devolver un cuerpo en formato JSON: no solo un código, sino un mensaje descriptivo.
  • Estandarizar el formato de respuesta de error: todas las respuestas de error deben seguir la misma estructura.
  • No exponer información sensible: nunca mostrar contraseñas, rutas internas del servidor ni stack traces completos.

3 Ejemplos de errores comunes

Error de validación (400 Bad Request)

POST /usuarios
Content-Type: application/json

{
  "nombre": "",
  "email": "correo_invalido"
}

Respuesta JSON

{
  "error": "Bad Request",
  "mensaje": "El campo 'nombre' es obligatorio y el email no es válido",
  "codigo": 400
}

Recurso no encontrado (404 Not Found)

GET /productos/9999

Respuesta JSON

{
  "error": "Not Found",
  "mensaje": "El producto con id 9999 no existe",
  "codigo": 404
}

Sin autorización (401 Unauthorized)

GET /pedidos

(sin enviar token de acceso)

Respuesta JSON

{
  "error": "Unauthorized",
  "mensaje": "Se requiere autenticación para acceder a este recurso",
  "codigo": 401
}

Error del servidor (500 Internal Server Error)

GET /usuarios

Respuesta JSON

{
  "error": "Internal Server Error",
  "mensaje": "Ocurrió un error inesperado en el servidor. Intente más tarde.",
  "codigo": 500
}

👉 Nota: el cliente no debería ver detalles internos como NullPointerException en UserService.

4 Estructura estandarizada para errores

Una buena práctica es definir un formato de error consistente.

Ejemplo recomendado

{
  "error": "Bad Request",
  "mensaje": "El campo 'email' es obligatorio",
  "codigo": 400,
  "detalles": [
    { "campo": "email", "problema": "formato inválido" }
  ],
  "timestamp": "2025-09-10T12:30:00Z",
  "ruta": "/usuarios"
}

Campos sugeridos

  • error: tipo genérico (ej. Bad Request, Not Found).
  • mensaje: descripción clara y legible.
  • codigo: número del status HTTP.
  • detalles: errores específicos (útil en validaciones).
  • timestamp: fecha/hora en que ocurrió el error.
  • ruta: endpoint que produjo el error.

5 Ejemplo en un flujo real

Petición

POST /productos
Content-Type: application/json

{
  "precio": -50
}

Respuesta

{
  "error": "Bad Request",
  "mensaje": "Faltan campos obligatorios y el precio debe ser mayor que 0",
  "codigo": 400,
  "detalles": [
    { "campo": "nombre", "problema": "obligatorio" },
    { "campo": "precio", "problema": "valor negativo" }
  ],
  "timestamp": "2025-09-10T14:00:00Z",
  "ruta": "/productos"
}

👉 Con esta respuesta, el cliente sabe exactamente qué corregir.

6 Manejo de errores en herramientas

En Postman

  • Si la API devuelve un error en JSON, Postman lo muestra formateado.
  • Se pueden crear tests automáticos para validar que los errores devuelvan el status correcto (pm.response.code === 400).

En cURL

curl -X POST https://api.tienda.com/productos ^
  -H "Content-Type: application/json" ^
  -d "{ \"precio\": -50 }"

Respuesta en consola

{
  "error": "Bad Request",
  "mensaje": "El precio debe ser mayor que 0",
  "codigo": 400
}

7 Buenas prácticas para manejo de errores en APIs REST

  • No devolver solo un número: 400. Incluir JSON con detalles del error.
  • Usar siempre el mismo formato de error: el cliente sabe qué esperar y cómo parsearlo.
  • Evitar mensajes ambiguos: mejor "El campo 'email' es obligatorio" que "Error en la petición".
  • No exponer detalles internos: los logs completos deben guardarse en el servidor, no enviarse al cliente.
  • Incluir un timestamp y la ruta: ayuda en la depuración y trazabilidad.
  • Documentar los posibles errores de cada endpoint: ejemplo, /usuarios puede devolver 400, 401, 404, 500.

8 Conclusión del capítulo

El manejo de errores en APIs REST es tan importante como el manejo de respuestas exitosas:

  • Un buen diseño de errores mejora la experiencia de los clientes de la API.
  • Los errores deben ser claros, consistentes y útiles.
  • La estandarización es clave: misma estructura de error en todos los endpoints.

👉 En resumen: los errores bien diseñados hacen que tu API sea profesional y fácil de usar.

Retornar