Errores Comunes
Esta página cubre los modos de fallo más comunes que los usuarios encuentran en EZY Integrations, organizados por categoría. Para cada síntoma encontrarás la causa probable, qué revisar en los Registros de Sincronización y la solución recomendada.
Errores de perfil de conexión
Sección titulada «Errores de perfil de conexión»Estos errores ocurren antes o durante la etapa de Ingestión, cuando el sistema no puede comunicarse con el sistema fuente o destino.
| Síntoma | Causa probable | Solución |
|---|---|---|
| La prueba de conexión devuelve “Autenticación fallida” | Las credenciales son incorrectas, han expirado o fueron revocadas. | Abre el perfil de conexión, vuelve a ingresar las credenciales y ejecuta la prueba nuevamente. |
| La prueba de conexión devuelve “Host no accesible” o agota el tiempo de espera | El nombre del host es incorrecto, el sistema está fuera de línea o un firewall bloquea el puerto. | Verifica el nombre del host y el puerto en el perfil. Confirma que el sistema fuente o destino está en funcionamiento y accesible desde el servidor de integración. |
| Error de protocolo TLS / SSL | El sistema destino usa un certificado autofirmado y la verificación TLS está habilitada. | Habilita Omitir validación TLS en el perfil de conexión solo si confías en el entorno de destino. No deshabilites la validación TLS en producción sin consultar a tu equipo de seguridad. |
| La prueba de conexión de SAP Business One falla | El host de base de datos, el nombre de la base de datos, el usuario o la contraseña son incorrectos; o el puerto SQL está bloqueado. | Verifica el host de SQL Server o HANA, el nombre de la base de datos y las credenciales de inicio de sesión. Confirma que el servidor de integración puede alcanzar el puerto de la base de datos en la red. |
| La prueba de conexión de Shopify falla con “Token inválido” | El token de acceso de la app personalizada de Shopify fue revocado, o se ingresaron credenciales OAuth incorrectas. | Regenera el token de acceso en el panel de administración de Shopify y actualiza el perfil de conexión. |
Qué revisar en los Registros de Sincronización: Un fallo en la etapa de Ingestión con un error de autenticación o red aparece en el detalle de error de la ejecución. El mensaje típicamente incluye el código de estado HTTP o el texto de la excepción de conexión.
Errores de mapeo
Sección titulada «Errores de mapeo»Estos errores ocurren en la etapa de Normalización o Transformación cuando la configuración de mapeo produce un resultado inesperado.
| Síntoma | Causa probable | Solución |
|---|---|---|
| ”Campo requerido faltante” en la etapa de Normalización | Un campo requerido por el formato canónico está vacío o ausente en los datos fuente. | Abre la configuración de mapeo y revisa el bloque de normalización. Agrega un campo estático o una ruta fuente alternativa para el campo faltante. |
| ”Tipo incompatible” o error de conversión | El campo fuente contiene un valor que el sistema no puede convertir al tipo esperado (por ejemplo, texto en un campo numérico). | Revisa los datos fuente de los registros afectados. Agrega un transformador de valor (como ToDecimal o ToString) en el bloque de transformación, o corrige los datos en el sistema fuente. |
| ”Ruta fuente desconocida” | Una ruta de campo en la configuración de mapeo hace referencia a una columna o propiedad que no existe en el payload fuente. | Abre el editor de configuración de mapeo. Usa el asistente de esquema (disponible para SAP B1) o verifica los nombres de campos del sistema fuente y corrige la ruta. |
| ”Tipo de entidad desconocido” | El nombre del tipo de entidad en la configuración de mapeo no coincide con ningún tipo admitido por el conector. | Verifica el nombre exacto del tipo de entidad en Tipos de Entidad y corrige la configuración de mapeo. |
| Falla la validación del campo destino | Un valor producido por la transformación supera el límite de longitud o el formato aceptado por el sistema destino. | Agrega un transformador (como Truncate o un transformador de formato) para ajustar el valor al rango aceptado por el destino. Consulta Transformadores de Valor. |
Qué revisar en los Registros de Sincronización: Los fallos de Normalización y Transformación aparecen por entidad en la vista de detalle de la ejecución. El mensaje de error indica la ruta del campo o el transformador que falló.
Fallos por etapa
Sección titulada «Fallos por etapa»| Etapa | Qué se ve en los Registros de Sincronización | Qué intentar a continuación |
|---|---|---|
| Ingestión | La ejecución muestra cero registros extraídos; el error hace referencia a un problema de conexión o consulta. | Verifica el perfil de conexión. Si usas SAP B1, revisa el SQL de extracción en la configuración de mapeo. Confirma que el sistema fuente tiene registros que coincidan con la ventana del cursor. |
| Normalización | La ejecución muestra registros extraídos pero un recuento de errores de normalización mayor que cero. | Abre la vista de detalle de la ejecución fallida y expande el error de entidad. Revisa el bloque de normalización en la configuración de mapeo. |
| Transformación | Los registros se normalizaron pero hay un recuento de errores de transformación mayor que cero. | Abre el error de entidad. Verifica el mapeo de campos, las opciones del transformador y los campos estáticos. Asegúrate de que cada campo destino requerido tenga una fuente de valor. |
| Ejecución | Los registros transformados son rechazados por el sistema destino. | Revisa el mensaje de error para ver el código de estado HTTP y el motivo de rechazo del destino. Un 400 suele indicar que un valor de campo es inválido; un 401 significa que las credenciales expiraron; un 429 indica que el trabajo superó el límite de velocidad del destino. |
| Finalización | La ejecución completa pero el cursor no avanza; o aparece un error de finalización. | Esto es poco frecuente. Contacta a tu contacto de soporte de EZY si los errores de finalización persisten después de que la Ejecución tenga éxito. |
Entradas en la Cola de Mensajes Fallidos (DLQ)
Sección titulada «Entradas en la Cola de Mensajes Fallidos (DLQ)»Cuando un registro falla todos los reintentos automáticos, se mueve a la Cola de Mensajes Fallidos. Los registros permanecen allí hasta que tomes una acción.
| Situación | Cuándo reintentar | Cuándo corregir la causa raíz primero |
|---|---|---|
| Categoría de error Auth | No — el reintento volverá a fallar. | Sí — rota o actualiza las credenciales en el perfil de conexión, luego reintenta. |
| Categoría de error Límite de velocidad | Sí — reintentar después de un tiempo suele funcionar. | Solo si los errores de límite de velocidad son frecuentes; considera reducir la frecuencia de ejecución. |
| Categoría de error Validación | No — los mismos datos incorrectos volverán a fallar. | Sí — corrige la configuración de mapeo o los datos en el sistema fuente, luego reintenta. |
| Categoría de error Transitorio | Sí — son fallos temporales de red o servicio. | Solo si los errores transitorios se repiten de forma constante. |
| Categoría de error Dependencia no lista | Sí — espera a que la entidad dependiente referenciada haya sido sincronizada al destino, luego reintenta. | Generalmente no es necesario; el sistema reintenta automáticamente los errores de dependencia. |
Consulta DLQ y Reintento para instrucciones detalladas de reintento.
Errores de autenticación y permisos
Sección titulada «Errores de autenticación y permisos»| Síntoma | Causa probable | Solución |
|---|---|---|
| ”Acceso denegado” al abrir un perfil de conexión o instancia | Tu cuenta de usuario no tiene permiso para gestionar ese recurso. | Solicita a tu administrador que te asigne el rol apropiado. Consulta Cuentas de Usuario. |
| No se puede eliminar una instancia | La instancia tiene historial de ejecuciones (registros de sincronización, ejecuciones o entradas en la DLQ). La eliminación está bloqueada para proteger el registro de auditoría. | Desactiva la instancia en lugar de eliminarla. |
| Clave de API rechazada en una solicitud entrante | La clave de API fue revocada o pertenece a un tenant diferente. | Genera una nueva clave de API. Consulta Claves de API. |
Qué puedes resolver tú vs. qué escalar
Sección titulada «Qué puedes resolver tú vs. qué escalar»| Puedes resolver por tu cuenta | Escala a tu contacto de soporte de EZY |
|---|---|
| Credenciales incorrectas en un perfil de conexión | Errores persistentes en la etapa de Finalización después de que otras etapas tienen éxito |
| Rutas de campo incorrectas o campos faltantes en una configuración de mapeo | El servicio de integración no procesa ninguna ejecución en todas las instancias |
| Claves de API o tokens OAuth expirados | Errores que hacen referencia al estado interno del sistema no visible en los Registros de Sincronización |
| Mensajes en la DLQ con categorías Validación o Límite de velocidad | Corrupción de datos o registros duplicados en el sistema destino |
| Desactivar una instancia que ya no debe ejecutarse | Facturación, aprovisionamiento de tenant o cambios de entorno |
Páginas relacionadas
Sección titulada «Páginas relacionadas»- Depuración de Ejecuciones — Guía paso a paso para diagnosticar una ejecución fallida.
- DLQ y Reintento — Cómo inspeccionar y reintentar mensajes de la Cola de Mensajes Fallidos.
- Contactar Soporte — Qué información preparar antes de escalar.
- Etapas del Pipeline — Referencia completa de cada etapa y qué puede fallar.