Definicion
Todos hemos pasado por eso: haces una llamada a una API y algo sale mal, pero el mensaje de error es completamente inútil. Quizás recibes {"error": "Bad request"} sin ninguna explicación de qué hiciste mal, o peor, un error 500 genérico sin ningún detalle. RFC 7807 (ahora actualizado por RFC 9457) existe para resolver este frustrante problema definiendo un formato estándar para las respuestas de error de APIs.
Antes de esta especificación, cada API inventaba su propia forma de reportar errores. Algunas usaban {"error": "mensaje"}, otras usaban {"message": "texto", "code": 123}, y algunas simplemente devolvían códigos de error crípticos. Esto convertía el manejo de errores en una pesadilla para los desarrolladores que integraban múltiples APIs. Tenías que escribir lógica de parseo personalizada para cada servicio.
RFC 7807 introduce “Problem Details” - un formato JSON estandarizado con campos específicos: type (una URI que identifica el tipo de error), title (un resumen legible por humanos), status (el código de estado HTTP), detail (una explicación específica de qué salió mal), e instance (qué recurso específico tuvo el problema). La belleza de este enfoque es que cualquier API que lo use devuelve errores exactamente en la misma estructura. Tu código de manejo de errores puede funcionar con Stripe, Twilio, o cualquier otra API que adopte el estándar sin modificaciones.
Ejemplo
Fallos de validación de formularios: En lugar de solo decir “validación fallida”, una API usando RFC 7807 te dice exactamente qué campo falló y por qué: {"type": "https://api.mitienda.com/errors/validation", "title": "Error de Validación", "detail": "El campo email debe contener una dirección de email válida", "instance": "/users/signup"}.
Errores de procesamiento de pagos: Cuando un pago falla, la API explica la razón específica: tarjeta rechazada, fondos insuficientes, tarjeta expirada - no solo “error de pago”. Los desarrolladores pueden mostrar mensajes apropiados a los usuarios y sugerir acciones.
Feedback de rate limiting: Cuando alcanzas el límite de peticiones de una API, RFC 7807 puede decirte exactamente cuándo puedes reintentar, cuántas peticiones te quedan, y qué endpoint activó el límite.
Problemas de autenticación: En lugar de un error 401 genérico, aprendes si tu token expiró, estaba mal formado, carecía de permisos, o fue emitido para la audiencia incorrecta.
Analogia
El Formulario Médico Estandarizado: Imagina si cada doctor usara el mismo formulario para documentar diagnósticos. Cualquier especialista que visites entendería inmediatamente tu historial médico. RFC 7807 es ese formulario estandarizado para errores de API - cada API habla el mismo “idioma de errores”.
El Panel de Retrasos del Aeropuerto: Las pantallas del aeropuerto muestran retrasos en un formato consistente: número de vuelo, hora original, nueva hora, razón del retraso, puerta. Instantáneamente sabes lo que necesitas. RFC 7807 te da esta misma información estructurada para errores de API.
El Sistema de Advertencias del Tablero del Coche: Los coches modernos no solo parpadean “PROBLEMA DE MOTOR”. Muestran códigos específicos que cualquier mecánico puede buscar, junto con el sistema afectado y la acción recomendada. Problem Details funciona igual - específico, accionable y universal.
El Informe del Inspector de Edificios: Un inspector de edificios no solo dice “no aprobado”. Proporciona un informe detallado: qué falló, dónde, por qué, y qué necesita arreglarse. RFC 7807 da a los desarrolladores este mismo nivel de detalle accionable.
Code Example
// Respuesta de error RFC 7807/9457
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 400 Bad Request
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/validation-error",
"title": "Tus parámetros de petición no validaron",
"status": 400,
"detail": "El campo 'email' debe ser una dirección de email válida",
"instance": "/users/123",
"invalidParams": [
{
"name": "email",
"reason": "debe ser un formato de email válido"
}
]
}
// Middleware de Express.js
app.use((err, req, res, next) => {
res.status(err.status || 500)
.type('application/problem+json')
.json({
type: err.type || 'about:blank',
title: err.title || 'Internal Server Error',
status: err.status || 500,
detail: err.message,
instance: req.path
});
});