La API sigue un enfoque estructurado para el manejo de errores, proporcionando retroalimentación útil cuando las solicitudes fallan debido a problemas de validación, violaciones de reglas de negocio u otras condiciones inesperadas. Aunque existen estándares internos para devolver errores, la implementación puede variar entre diferentes consultas/mutaciones.
Comportamiento de la respuesta y códigos de estado HTTP
En la mayoría de los casos, la API devuelve un estado HTTP 200 OK incluso cuando ocurre un error. Esto se debe a que los errores de GraphQL se manejan dentro del cuerpo de la respuesta y no a través de los códigos de estado HTTP. Una de las excepciones es el Código de Estado 429 - Demasiadas Solicitudes, que se devuelve cuando se exceden los límites de uso. También pueden usarse otros códigos de estado, como los que indican problemas de autenticación o disponibilidad.
Errores de validación
Si la entrada no cumple con los requisitos esperados, como cuando no se siguen las reglas de negocio, la respuesta incluirá una lista de errores de validación. Para las mutaciones que realizan validación de entrada, la respuesta normalmente sigue esta estructura:
type UpdateActivityResult {
validationErrors: [ValidationErrors]
item: Activity
}Cuando la validación falla, la propiedad item generalmente se establece en su valor predeterminado, y la propiedad validationErrors proporciona detalles sobre el problema. El campo message ofrece orientación útil.
Ejemplo: Respuesta de error de validación
{
"data": {
"updateActivity": {
"item": null,
"validationErrors": [
{
"message": "ActivityDate debe tener el formato 'yyyy-MM-dd HH:mm:ss'",
"propertyName": "ActivityDate"
}
]
}
}
}Errores generales
Los errores que no están relacionados con la validación, como fallos internos de procesamiento, problemas con servicios externos o condiciones inesperadas, se devuelven en la colección errors de la respuesta de GraphQL.
Estos errores normalmente incluyen lo siguiente:
- Mensaje: Una descripción del error.
- Extensiones: Metadatos adicionales como códigos de error o información contextual.
Ejemplo: Respuesta de error general
{
"data": {
"addActivity": null
},
"errors": [
{
"message": "La solicitud del método falló con [220] El formato de la marca de tiempo debe ser yyyy-mm-dd hh:mm:ss[.fffffffff] para addActivity",
"extensions": {
"code": "APP_SERVER_METHOD",
"data": {
"activityId": "00-ebaa2c159c436a4a8e4c6bd086e33b2b-4927fca7e17ec948-00"
}
}
}
]
}Consideraciones
- Aunque generalmente se siguen los estándares mencionados arriba, algunas consultas/mutaciones pueden no estar completamente alineadas aún. El Cliente de Terceros debe manejar tanto los errores de validación estructurados como los errores generales de GraphQL de manera adecuada.
- El Cliente de Terceros siempre debe revisar el cuerpo de la respuesta para obtener detalles de los errores en lugar de depender únicamente de los códigos de estado HTTP.