Manejo de errores en REST API: Códigos de estado y objetos de error
Un buen manejo de errores en REST API ayuda a los desarrolladores a entender, localizar y resolver problemas rápidamente, sin necesidad de adivinar.
Descripción compacta
El manejo de errores en REST API describe cómo una interfaz responde a solicitudes inválidas, problemas técnicos y violaciones de reglas de negocio. Esto incluye el código de estado HTTP correcto, una respuesta de error estructurada e identificación única del error. RFC 7807 define con Problem Details un formato estándar para respuestas de error que incluye campos como type, title, status, detail e instance. Un buen manejo de errores es consistente en todos los endpoints, contiene información suficiente para desarrolladores y no revela detalles internos de seguridad. Reduce el esfuerzo de soporte, mejora la experiencia del desarrollador y permite que los clientes clasifiquen errores automáticamente y reaccionen apropiadamente.
Cuando trabajas con APIs, los errores del lado del servidor son tus mayores adversarios. Un proveedor puede tener límites de tokens y solicitudes, por ejemplo Langdock, y además utilizan Cloudflare que tiene sus propios límites y reglas. Cuando tus solicitudes se evalúan solo parcialmente o de forma esporádica, el debugging es crucial. Qué respuesta obtienes y qué significa.
Componentes importantes
Códigos de estado HTTP correctos
Los códigos de estado HTTP son la primera información que recibe un cliente sobre el éxito o fracaso de una solicitud. Los códigos 4xx indican errores del cliente, los códigos 5xx indican errores del servidor. Los códigos 4xx importantes son 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Content y 429 Too Many Requests. Los códigos 5xx como 500 Internal Server Error, 502 Bad Gateway y 503 Service Unavailable apuntan a problemas del lado del servidor.
Problem Details según RFC 7807
RFC 7807 define un formato estándar para respuestas de error. Un Problem Detail contiene como mínimo type, title, status y detail. Opcionalmente se pueden añadir instance para la URI defectuosa y extensiones adicionales. El Content-Type es application/problem+json. El formato permite que los clientes analicen y representen errores de forma uniforme.
Identificadores de error únicos
Cada respuesta de error debe contener un ID de error único, por ejemplo una UUID o una ID de correlación. Esto permite rastrear errores en logs y sistemas de monitoreo sin revelar detalles internos. El cliente puede proporcionar el ID de error al soporte técnico.
Categorías de error y códigos
Además de los códigos de estado HTTP, las respuestas de error deben incluir códigos de error específicos de la aplicación. Un código como ORDER_NOT_FOUND o PAYMENT_DECLINED es más preciso que un 404 genérico. Estos códigos ayudan a los clientes a reaccionar específicamente ante situaciones determinadas.
Errores de validación
En caso de errores de validación, la respuesta debe indicar los campos defectuosos y el motivo. Por ejemplo: field: email, message: Formato de correo electrónico inválido. Esto permite corregir formularios directamente en el cliente.
Errores sin revelar detalles internos
Los mensajes de error deben ser informativos pero no deben contener rutas internas, stack traces o detalles de bases de datos. Esta información puede ayudar a atacantes. Los detalles internos pertenecen a los logs, no a la respuesta de la API.
Localización e idioma
Los mensajes de error pueden depender del idioma. El cliente debe comunicar a través del header Accept-Language qué idioma espera. El servidor responde entonces con mensajes localizados apropiadamente, si están disponibles.
Información de reintento
Para errores temporales como 429 o 503, el servidor debe comunicar a través del header Retry-After cuándo el cliente puede reintentar la solicitud. Esto previene reintentos incontrolados y reduce la carga del servidor.
Logging y monitoreo
Cada error debe registrarse en el lado del servidor con contexto, incluyendo request ID, timestamp, endpoint, código de estado y detalles del error. Los sistemas de monitoreo pueden generar alertas y detectar tendencias de errores basándose en esto.
Consistencia en todos los endpoints
Todos los endpoints de una API deben usar el mismo formato de error. Una estructura uniforme facilita la implementación del cliente y el manejo de errores. Las desviaciones llevan a código especial innecesario y mayor potencial de fallos.
Ejemplo práctico
Un cliente envía una solicitud para crear un pedido con datos inválidos:
POST /api/v1/orders
Content-Type: application/json
{
"customerId": 123,
"items": [
{ "productId": 42, "quantity": 0 }
]
}La API responde con 422 Unprocessable Content y un Problem Detail:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
{
"type": "https://api.shop.de/problems/validation-error",
"title": "Validierungsfehler",
"status": 422,
"detail": "Die Bestellung enthält ungültige Daten.",
"instance": "/api/v1/orders",
"errors": [
{
"field": "items[0].quantity",
"code": "QUANTITY_TOO_LOW",
"message": "Die Menge muss mindestens 1 betragen."
}
]
}El cliente puede reconocer directamente qué campo es incorrecto y por qué. La X-Request-ID ayuda al soporte a localizar el error en los logs. El formato de error es consistente y legible por máquinas.
FAQ: Manejo de errores en REST API
1. ¿Qué es un Problem Detail según RFC 7807?
2. ¿Por qué las APIs deben usar formatos de error uniformes?
3. ¿Qué debe incluir una respuesta de error?
4. ¿Cuál es la diferencia entre 400 y 422?
5. ¿Cuándo se usa 401 y cuándo 403?
6. ¿Qué es 409 Conflict?
7. ¿Deben enviarse stack traces en respuestas de error?
8. ¿Qué es una ID de correlación?
9. ¿Cuál es la ventaja de códigos de error específicos de la aplicación?
10. ¿Qué es 429 Too Many Requests?
11. ¿Cómo se manejan los errores del lado del servidor?
12. ¿Qué es el header Retry-After?
13. ¿Deben localizarse los mensajes de error?
14. ¿Cuál es la diferencia entre title y detail?
15. ¿Cómo se prueban los casos de error de una API?
Continuamos en la ruta de aprendizaje de APIs, hacia la versionación.
El siguiente artículo en la ruta de aprendizaje de APIs trata sobre versionación de APIs — estrategias para REST, GraphQL y gRPC, además de migración entre versiones de APIs.
Referencias
- https://www.rfc-editor.org/rfc/rfc7807
- https://www.rfc-editor.org/rfc/rfc9110
- https://opensource.zalando.com/restful-api-guidelines/index.html
Lecturas recomendadas sobre desarrollo de APIs
Si deseas profundizar en manejo de errores en APIs, diseño de APIs y arquitectura de software, te recomendamos los siguientes libros:
Keine Bücher für Kategorie "api-development" gefunden.