TL;DR
RFC 9457 (Problem Details for HTTP APIs) es el formato estándar para las respuestas de error de la API. Reemplaza los formatos de error personalizados con una estructura consistente: tipo, título, estado, detalle e instancia. Modern PetstoreAPI implementa RFC 9457 en todas las respuestas de error con negociación de contenido adecuada y detalles de validación.
Introducción
Tu API devuelve un error. ¿Cómo es la respuesta? Si eres como la mayoría de las API, inventaste tu propio formato:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Cada API tiene un formato de error diferente. Los clientes necesitan un manejo de errores personalizado para cada API. No hay una forma estándar de analizar los errores, mostrarlos a los usuarios o registrarlos para la depuración.
RFC 9457 resuelve esto. Es un estándar IETF que define cómo las API deben devolver los errores. En lugar de inventar tu propio formato, utilizas un estándar probado que los clientes ya entienden.
El antiguo Swagger Petstore usaba formatos de error personalizados sin consistencia. Modern PetstoreAPI implementa RFC 9457 en todas las respuestas de error, proporcionando detalles de error estructurados y legibles por máquina.
En esta guía, aprenderás qué es RFC 9457, cómo implementarlo correctamente y cómo Modern PetstoreAPI lo utiliza para todas las respuestas de error.
El problema del error de la API
Antes de RFC 9457, cada API inventaba su propio formato de error.
Variaciones comunes del formato de error
Formato 1: Mensaje simple
{"error": "User not found"}
Formato 2: Código y mensaje
{"code": "USER_NOT_FOUND", "message": "User not found"}
Formato 3: Estructura anidada
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Formato 4: Array de errores
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Problemas con los formatos personalizados
1. Sin consistencia: Los clientes necesitan un análisis personalizado para cada API.
2. Información faltante: Algunos formatos carecen de códigos de error, algunos de detalles, algunos de ambos.
3. Sin estructura legible por máquina: Difícil de manejar errores programáticamente.
4. Poca internacionalización: Los mensajes de error están codificados en inglés.
5. Sin estándar para errores de validación: Cada API maneja los errores a nivel de campo de manera diferente.
¿Qué es RFC 9457?
RFC 9457 (publicado en julio de 2023) define "Detalles del problema para las API HTTP". Es un estándar IETF que especifica cómo las API deben estructurar las respuestas de error.
Características clave
Tipo de medio estándar: application/problem+json (o application/problem+xml)
Estructura consistente: Todos los errores siguen el mismo formato
Legible por máquina: Los clientes pueden analizar errores programáticamente
Extensible: Puedes añadir campos personalizados manteniendo la compatibilidad
Consciente de HTTP: Se integra con los códigos de estado HTTP
RFC 9457 vs. errores personalizados
Error personalizado:
{"error": "Email is required"}
Error RFC 9457:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
La versión RFC 9457 proporciona:
- URL del tipo de error para la documentación
- Título legible por humanos
- Código de estado HTTP
- Explicación detallada
- Ruta de la solicitud que causó el error
- Detalles de validación a nivel de campo
Estructura RFC 9457 explicada
RFC 9457 define cinco campos estándar y permite extensiones personalizadas.
Campos estándar
1. type (string, requerido)
Una referencia URI que identifica el tipo de error. Debe apuntar a documentación legible por humanos.
"type": "https://petstoreapi.com/errors/validation-error"
Si se omite, el valor predeterminado es about:blank.
2. title (string, requerido)
Un resumen corto y legible por humanos del tipo de error. No debe cambiar entre ocurrencias.
"title": "Validation Error"
3. status (número, requerido)
El código de estado HTTP. Incluido para mayor comodidad, de modo que los clientes no necesiten analizar los encabezados.
"status": 400
4. detail (string, opcional)
Una explicación legible por humanos específica para esta ocurrencia del error.
"detail": "The email field must be a valid email address"
5. instance (string, opcional)
Una referencia URI que identifica la ocurrencia específica del error. A menudo es la ruta de la solicitud.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Extensiones personalizadas
Puedes añadir campos personalizados para contexto adicional:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Cómo Modern PetstoreAPI implementa RFC 9457
Modern PetstoreAPI utiliza RFC 9457 para todas las respuestas de error.
Ejemplo 1: Recurso no encontrado
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
Ejemplo 2: Error de autenticación
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
Ejemplo 3: Límite de tasa excedido
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
Consulta la documentación de manejo de errores de Modern PetstoreAPI para todos los tipos de error.
Errores de validación con RFC 9457
Los errores de validación necesitan detalles a nivel de campo. RFC 9457 permite extensiones personalizadas para esto.
Formato de validación de Modern PetstoreAPI
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
Puntos clave
array de errores: Contiene detalles de validación a nivel de campo
field: La ruta JSON al campo no válido
message: Mensaje de error legible por humanos
code: Código de error legible por máquina
rejectedValue: El valor que fue rechazado (opcional)
Este formato permite a los clientes:
- Mostrar errores a nivel de campo en formularios
- Resaltar campos no válidos
- Proporcionar mensajes de error específicos
- Manejar errores programáticamente
Prueba de respuestas de error con Apidog
Apidog te ayuda a probar el cumplimiento de RFC 9457.
Caso de prueba: Error de validación
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
Caso de prueba: URLs de tipo de error
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
Migración de formatos de error personalizados
Si estás utilizando formatos de error personalizados, aquí te explicamos cómo migrar a RFC 9457.
Paso 1: Añadir encabezado Content-Type
Comienza a devolver application/problem+json:
Content-Type: application/problem+json
Paso 2: Mapear campos existentes
Mapea tu formato personalizado a RFC 9457:
Antes:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
Después:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
Paso 3: Soportar ambos formatos (período de transición)
Utiliza la negociación de contenido para soportar ambos formatos:
Accept: application/json → Devuelve formato personalizado
Accept: application/problem+json → Devuelve formato RFC 9457
Paso 4: Depreciar formato personalizado
Después de que los clientes migren, deprecia el formato personalizado y devuelve RFC 9457 por defecto.
Conclusión
RFC 9457 proporciona un formato estándar para las respuestas de error de la API. Reemplaza los formatos de error personalizados con una estructura consistente y legible por máquina que los clientes pueden analizar programáticamente.
Modern PetstoreAPI implementa RFC 9457 en todas las respuestas de error, demostrando cómo estructurar los errores correctamente con detalles de validación adecuados, URLs de tipo de error y códigos de estado HTTP.
Utiliza Apidog para probar el cumplimiento de RFC 9457, validar estructuras de error y asegurar que tu API devuelve respuestas de error adecuadas.
Preguntas frecuentes
¿Es RFC 9457 obligatorio para las API REST?
No, pero es el estándar recomendado. Usar RFC 9457 hace que tu API sea más consistente y fácil de integrar para los clientes.
¿Puedo usar RFC 9457 con XML?
Sí, RFC 9457 define formatos tanto JSON (application/problem+json) como XML (application/problem+xml).
¿Debería incluir siempre los cinco campos estándar?
type, title y status son obligatorios. detail e instance son opcionales pero recomendados para un mejor contexto del error.
¿Puedo añadir campos personalizados a las respuestas RFC 9457?
Sí, RFC 9457 es extensible. Puedes añadir campos personalizados como errors, retryAfter o traceId para contexto adicional.
¿Cómo manejo los errores de validación con RFC 9457?
Añade un array personalizado de errors con detalles a nivel de campo. Modern PetstoreAPI muestra este patrón en sus respuestas de error de validación.
¿A qué debería apuntar la URL del tipo de error?
Debería apuntar a documentación legible por humanos que explique el tipo de error, las posibles causas y cómo solucionarlo.
¿Necesito cambiar los códigos de estado HTTP cuando uso RFC 9457?
No, RFC 9457 funciona con códigos de estado HTTP estándar. El campo status en la respuesta debe coincidir con el código de estado HTTP.
¿Cómo pruebo el cumplimiento de RFC 9457?
Utiliza Apidog para validar la estructura de la respuesta de error, verificar los campos obligatorios y comprobar que los tipos de contenido coinciden con las especificaciones de RFC 9457.