Referencia completa de todos los códigos de error en la API GraphQL de Blue, organizada por categoría
La API GraphQL de Blue devuelve errores en un formato estandarizado siguiendo la especificación de GraphQL. Cuando ocurre un error, la respuesta incluye un errors array con información detallada sobre lo que salió mal.
Ejemplo de Respuesta de Error
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
Estructura del Error
Cada objeto de error contiene:
- mensaje: Una descripción legible por humanos del error
- extensions.code: Un código de error legible por máquina para el manejo programático
Seguridad de Errores en Producción
Blue implementa un sistema de seguridad para la exposición de errores:
- Errores Seguros: Mostrar códigos de error y mensajes reales a los clientes
- Errores No Seguros: Devolver
INTERNAL_SERVER_ERROR genéricos para ocultar detalles sensibles
- Recurso No Encontrado: Todos los errores
*_NOT_FOUND se consideran seguros y siempre se exponen
Categorías de Errores
Blue define 108 códigos de error personalizados organizados en las siguientes categorías:
Errores de Autenticación y Autorización
| Código de Error |
Mensaje |
Descripción |
UNAUTHENTICATED |
"Se requiere autenticación." |
La solicitud requiere autenticación pero no se proporcionó ninguna |
FORBIDDEN |
"No estás autorizado." |
Autenticado pero carece de los permisos requeridos |
Errores de Recurso No Encontrado (52 en total)
Recursos Principales
| Código de Error |
Mensaje |
Descripción |
TODO_NOT_FOUND |
"Todo no fue encontrado." |
El registro/todo no existe o el usuario carece de acceso |
TODO_LIST_NOT_FOUND |
"La lista de todo no fue encontrada." |
La lista no existe o el usuario carece de acceso |
PROJECT_NOT_FOUND |
"El proyecto no fue encontrado." |
El proyecto no existe o el usuario carece de acceso |
COMPANY_NOT_FOUND |
"La empresa no fue encontrada." |
La empresa no existe o el usuario carece de acceso |
USER_NOT_FOUND |
"El usuario no fue encontrado." |
El usuario no existe en el sistema |
| Código de Error |
Mensaje |
Descripción |
CUSTOM_FIELD_NOT_FOUND |
"El campo personalizado no fue encontrado." |
El campo personalizado no existe |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"La opción de campo personalizado no fue encontrada." |
La opción de campo de selección no existe |
FORM_NOT_FOUND |
"El formulario no fue encontrado." |
La plantilla del formulario no existe |
FORM_FIELD_NOT_FOUND |
"El campo del formulario no fue encontrado." |
El campo del formulario no existe |
Componentes del Proyecto
| Código de Error |
Mensaje |
Descripción |
TAG_NOT_FOUND |
"La etiqueta no fue encontrada." |
La etiqueta no existe en el proyecto |
AUTOMATION_NOT_FOUND |
"La automatización no fue encontrada." |
La regla de automatización no existe |
CHART_NOT_FOUND |
"El gráfico no fue encontrado." |
El gráfico del tablero no existe |
WEBHOOK_NOT_FOUND |
"El webhook no fue encontrado." |
La configuración del webhook no existe |
TEMPLATE_NOT_FOUND |
"La plantilla no fue encontrada." |
La plantilla del proyecto no existe |
Comentarios y Actividades
| Código de Error |
Mensaje |
Descripción |
COMMENT_NOT_FOUND |
"El comentario no fue encontrado." |
El comentario no existe |
ACTIVITY_NOT_FOUND |
"La actividad no fue encontrada." |
La entrada del registro de actividad no existe |
REACTION_NOT_FOUND |
"La reacción no fue encontrada." |
La reacción del comentario no existe |
Otros Recursos
| Código de Error |
Mensaje |
Descripción |
FILE_NOT_FOUND |
"El archivo no fue encontrado." |
El archivo adjunto no existe |
SUBSCRIPTION_NOT_FOUND |
"La suscripción no fue encontrada." |
La suscripción de facturación no existe |
INVOICE_NOT_FOUND |
"La factura no fue encontrada." |
El registro de la factura no existe |
CHECKLIST_NOT_FOUND |
"La lista de verificación no fue encontrada." |
La lista de verificación no existe |
CHECKLIST_ITEM_NOT_FOUND |
"El elemento de la lista de verificación no fue encontrado." |
El elemento de la lista de verificación no existe |
PROJECT_ROLE_NOT_FOUND |
"El rol del proyecto no fue encontrado." |
El rol personalizado del proyecto no existe |
PROJECT_ACCESS_NOT_FOUND |
"El acceso al proyecto no fue encontrado." |
El acceso del usuario al proyecto no existe |
NOTIFICATION_NOT_FOUND |
"La notificación no fue encontrada." |
La notificación no existe |
DASHBOARD_NOT_FOUND |
"El tablero no fue encontrado." |
El tablero no existe |
KEY_NOT_FOUND |
"La clave no fue encontrada." |
La clave de configuración no existe |
Errores de Validación
| Código de Error |
Mensaje |
Descripción |
BAD_USER_INPUT |
"Entrada no válida." |
Fallo de validación de entrada genérico |
VALIDATION_ERROR |
"Parámetros no válidos" |
Los parámetros de la solicitud fallaron la validación |
BAD_EMAIL |
"Necesitas ingresar un correo electrónico válido." |
Formato de correo electrónico no válido |
INVALID_IDS |
"IDs no válidos." |
Uno o más IDs en la solicitud son inválidos |
PHONE_INVALID |
"El teléfono es inválido." |
Formato de número de teléfono no válido |
URL_INVALID |
"La URL es inválida." |
Formato de URL no válido |
INVALID_RECURRING_DUE_DATE |
"Fecha de vencimiento no válida para tarea recurrente" |
Fallo de validación de fecha de tarea recurrente |
INVALID_COLOR |
"Color no válido" |
El valor del color no coincide con el formato esperado |
Errores de Lógica Empresarial
Límites y Cuotas
| Código de Error |
Mensaje |
Descripción |
COMPANY_LIMIT |
"Has alcanzado el límite de empresas para tu cuenta." |
Límite máximo de empresas alcanzado |
PROJECT_LIMIT |
"Has alcanzado el límite de proyectos para tu empresa." |
Límite máximo de proyectos alcanzado |
USER_LIMIT |
"Has alcanzado el límite de usuarios para tu empresa." |
Límite máximo de usuarios alcanzado |
PROJECT_TEMPLATE_LIMIT |
"Has alcanzado el límite de plantillas para tu empresa." |
Límite máximo de plantillas alcanzado |
CUSTOM_FIELD_LIMIT |
"Límite de campos personalizados alcanzado." |
Límite máximo de campos personalizados alcanzado |
TODO_LIST_LIMIT |
"Has alcanzado el límite de listas para tu proyecto." |
Límite máximo de listas por proyecto |
TOO_MANY_TODOS |
"Demasiados todos." |
Límite de registros excedido |
TOO_MANY_OPTIONS |
"Demasiadas opciones." |
Límite de opciones de campo de selección excedido |
MAX_FILE_SIZE |
"El tamaño máximo del archivo es de 4.8gb" |
Límite de tamaño de carga de archivo excedido |
Conflictos de Recursos
| Código de Error |
Mensaje |
Descripción |
TAG_ALREADY_EXISTS |
"La etiqueta ya existe." |
La etiqueta con el mismo nombre existe en el proyecto |
COMPANY_SLUG_ALREADY_EXISTS |
"La empresa ya existe." |
El slug/URL de la empresa está ocupado |
USER_ALREADY_EXISTS |
"El usuario ya existe." |
El correo electrónico del usuario ya está registrado |
ALREADY_INVITED |
"El usuario ya está invitado." |
El usuario ya tiene una invitación pendiente |
USER_ALREADY_IN_PROJECT |
"El usuario ya está en este proyecto." |
El usuario ya tiene acceso al proyecto |
FILE_TYPE_NOT_ALLOWED |
"Tipo de archivo no permitido." |
El tipo de archivo subido está restringido |
Errores de Permiso y Acceso
| Código de Error |
Mensaje |
Descripción |
UNABLE_TO_DELETE_ONLY_ADMIN |
"No se puede eliminar al único administrador de la empresa." |
No se puede eliminar al último administrador |
UNABLE_TO_UPDATE_OWNER |
"No se puede actualizar el PROPIETARIO." |
No se pueden modificar los permisos del propietario |
TODO_LIST_IS_HIDDEN |
"La lista de todo está oculta." |
Lista oculta del rol del usuario |
COMPANY_NOT_ACTIVE |
"La empresa no está activa." |
Suscripción de la empresa inactiva |
PROJECT_NOT_ACTIVE |
"El proyecto no está activo." |
El proyecto está archivado/inactivo |
Errores de Integridad de Datos
| Código de Error |
Mensaje |
Descripción |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"No se puede eliminar la lista con todos." |
La lista debe estar vacía para eliminar |
UNABLE_TO_DELTE_FILE |
"No se puede eliminar el archivo." |
Fallo en la eliminación del archivo (error tipográfico en el código) |
UNABLE_TO_MOVE_TODO |
"No se puede mover el todo." |
No se puede mover el registro entre listas |
DEPENDENCY_HAS_DEPENDENCY |
"La dependencia tiene dependencia" |
Se detectó una dependencia circular |
TODO_DEPENDS_ON_ITSELF |
"El todo depende de sí mismo" |
Dependencia autorreferencial |
Errores de Stripe/Pago
| Código de Error |
Mensaje |
Descripción |
STRIPE_CREATING_CUSTOMER |
"Error al crear el cliente en stripe." |
Fallo en la creación del cliente de Stripe |
STRIPE_ALREADY_SUBSCRIBED |
"Ya suscrito." |
Existe una suscripción activa |
STRIPE_MISSING_PAYMENT_METHOD |
"Método de pago faltante." |
No hay método de pago en el archivo |
STRIPE_CREATING_SUBSCRIPTION |
"Error al crear la suscripción en stripe." |
Fallo en la creación de la suscripción |
STRIPE_UPDATING_SUBSCRIPTION |
"Error al actualizar la suscripción en stripe." |
Fallo en la actualización de la suscripción |
STRIPE_CHECKOUT_SESSION |
"Error al crear la sesión de pago en stripe." |
Fallo en la creación de la sesión de pago |
STRIPE_CUSTOMER_PORTAL |
"Error al crear el portal del cliente en stripe." |
Fallo en la creación de la sesión del portal |
STRIPE_TAX_ID |
"No se puede guardar el ID fiscal" |
Fallo en la validación/guardado del ID fiscal |
PAYMENT_REQUIRED |
"Se requiere pago." |
La función requiere una suscripción activa |
NO_PAYMENT_REQUIRED |
"No se requiere pago." |
No se necesita pago para la operación |
Errores de Autenticación y Sesión
| Código de Error |
Mensaje |
Descripción |
INVALID_CREDENTIALS |
"Credenciales no válidas." |
Nombre de usuario/contraseña incorrectos |
EXPIRED_RESET_TOKEN |
"El token de restablecimiento ha expirado." |
El token de restablecimiento de contraseña ha expirado |
OAUTH_FAILED |
"El proceso de OAuth falló." |
Fallo en la autenticación de OAuth |
SAML_NOT_ENABLED |
"SSO (SAML) no está habilitado." |
SSO SAML no configurado |
SSO_AUTO_PROVISION_DISABLED |
"La provisión automática está deshabilitada." |
No se pueden crear automáticamente usuarios SSO |
Limitación de Tasa
La limitación de tasa es manejada por el graphql-rate-limit paquete con diferentes configuraciones:
| Tipo de Límite |
Ventana |
Máx. Solicitudes |
Aplicado a |
| Standard |
60s |
500 |
Most queries/mutations |
| Sensitive |
300s |
10 |
Password reset, auth operations |
| Expensive |
60s |
20 |
Complex queries, bulk operations |
| Search |
60s |
60 |
Search operations |
| File Upload |
60s |
100 |
File upload operations |
Cuando se limita la tasa, recibirás un error estándar de GraphQL con un mensaje indicando que se ha superado el límite.
Errores del Sistema e Internos
| Código de Error |
Mensaje |
Descripción |
INTERNAL_SERVER_ERROR |
"Error interno del servidor." |
Error genérico para errores no seguros en producción |
UNKNOWN_ERROR |
"Error desconocido." |
Ocurrió un error inesperado |
RESOLVER_NOT_FOUND |
"Resolver no encontrado" |
Falta el resolver de GraphQL |
FIELD_NOT_IN_SCHEMA |
"Campo no en el esquema" |
El campo solicitado no existe |
Mejores Prácticas para el Manejo de Errores
Manejo del Lado del Cliente
try {
const result = await client.mutate({
mutation: CREATE_TODO,
variables: { input }
});
} catch (error) {
if (error.graphQLErrors?.length > 0) {
const errorCode = error.graphQLErrors[0].extensions?.code;
switch (errorCode) {
case 'UNAUTHENTICATED':
// Redirect to login
break;
case 'TODO_NOT_FOUND':
// Show "Record not found" message
break;
case 'VALIDATION_ERROR':
// Display validation errors
break;
default:
// Show generic error message
}
}
}
Escenarios Comunes de Error
- Se requiere autenticación:
UNAUTHENTICATED - El usuario necesita iniciar sesión
- Permiso denegado:
FORBIDDEN - El usuario carece del rol/permisos requeridos
- Recurso no encontrado:
*_NOT_FOUND - El recurso no existe o el usuario no puede acceder a él
- Fallo de validación:
VALIDATION_ERROR, BAD_USER_INPUT - Verifica los parámetros de entrada
- Limitado por tasa: Verifica los encabezados de límite de tasa e implementa retroceso
- Se requiere pago:
PAYMENT_REQUIRED - La función requiere suscripción
Documentación Relacionada