DLQ y Reintento de Mensajes

Cuando un registro falla en cualquier etapa del pipeline y se agotan todos los reintentos automáticos, se mueve a la Cola de Mensajes Muertos (DLQ). Los registros en la DLQ no se pierden — se conservan con su payload completo y los detalles del error. Una vez que hayas identificado y corregido la causa subyacente, puedes reintentar los registros para enviarlos nuevamente por el pipeline.

Qué envía un registro a la DLQ

Un registro llega a la DLQ cuando falla en cada intento de reintento automático. Las causas más comunes incluyen:

• Errores permanentes — el sistema destino rechazó el registro (por ejemplo: un error de validación, un campo requerido faltante en el mapeo o un conflicto con un registro existente). No pueden resolverse reintentando sin un cambio en el mapeo.
• Errores transitorios — una condición temporal como un tiempo de espera del sistema destino o una interrupción de red. Se reintentan automáticamente; si los reintentos se agotan antes de que el sistema se recupere, el registro llega a la DLQ.
• Errores desconocidos — fallas inesperadas que no corresponden a un patrón conocido. Inspecciona el mensaje de error para determinar el siguiente paso.

Acceder a la página DLQ

En la navegación izquierda, selecciona Dead Letter Queue. La página muestra todos los registros fallidos pendientes de todas las instancias de tu tenant, con un contador que indica cuántos están en espera.

La lista DLQ

La lista muestra las siguientes columnas:

Columna	Descripción
Category	La categoría del error: Transient (reintentable), Permanent (requiere corrección antes del reintento) o Unknown.
Instance	La instancia a la que pertenece el registro fallido, con las etiquetas de sistema fuente → destino.
Entity	El tipo de entidad del registro fallido (p. ej., item, order).
Source ID	El identificador del registro en el sistema fuente.
Error	Un extracto breve del mensaje de error. Haz clic en la fila para ver el mensaje completo.
Retries	Cuántas veces se reintentó el registro antes de colocarse en la DLQ. Los valores de 3 o más se destacan en ámbar; los de 5 o más en rojo.
Status	Pending (aún no reintentado), Replayed (reintento enviado) o Discarded (eliminado de forma permanente).
Created	Hace cuánto tiempo entró el registro en la DLQ.

Filtrar la DLQ

Usa los controles de filtro sobre la tabla para reducir la lista:

Filtro	Descripción
Instance	Muestra registros de una instancia específica solamente.
Entity Type	Muestra registros de un tipo de entidad específico (disponible después de seleccionar una instancia).
Error Category	Filtra por Transient, Permanent o Unknown.

Haz clic en Clear Filters para restablecer todos los filtros a la vez.

Inspeccionar un registro fallido

Haz clic en cualquier fila para abrir el panel de detalles de ese registro. El panel muestra:

• Instancia y flujo fuente → destino
• Tipo de entidad y Source ID
• Categoría del error y conteo de reintentos
• Mensaje de error completo — el error exacto devuelto por el sistema destino o por la etapa del pipeline
• Payload original — el payload completo del mensaje en el punto de falla, mostrado como JSON con formato. Usa el botón de copiar para copiar el payload completo o solo la sección del payload destino al portapapeles. Usa el botón de expandir para ver el payload en pantalla completa.

Reintentar un registro fallido

El reintento envía el registro fallido de vuelta por el pipeline desde el principio (etapa Ingest). Antes de reintentar, corrige la causa subyacente — por ejemplo, corrige el mapeo de campos, reactiva el sistema destino o resuelve el problema de autenticación.

Para reintentar un registro individual:

1. Haz clic en la fila del registro para abrir el panel de detalles.
2. Revisa el mensaje de error y confirma que la causa haya sido resuelta.
3. Opcionalmente habilita Re-extract from source para obtener una copia actualizada del registro desde el sistema fuente antes de enviarlo por el pipeline. Usa esta opción cuando el registro fuente puede haber cambiado desde el fallo.
4. Haz clic en Replay. El estado del registro cambia a Replayed.

Para reintentar registros seleccionados:

1. Marca las casillas junto a los registros que deseas reintentar.
2. La barra de herramientas sobre la tabla se activa con Replay Selected (N).
3. Opcionalmente habilita el toggle Re-extract from source en la barra de filtros.
4. Haz clic en Replay Selected. No se requiere confirmación para el reintento en lote.

Para reintentar todos los registros (con filtros opcionales):

1. Aplica filtros para reducir el alcance si es necesario.
2. Haz clic en Replay All (o Replay All Filtered cuando haya filtros activos).
3. Confirma la acción en el diálogo.
4. Todos los registros pendientes que coincidan se ponen en cola para reintento.

Cuándo no reintentar

• No reintentar errores de categoría Permanent sin antes corregir la causa raíz. El registro fallará nuevamente de inmediato y regresará a la DLQ.
• No reintentar registros si el sistema destino ya recibió los datos por otro medio — el reintento intentará escribir el registro de nuevo y puede generar duplicados dependiendo del manejo de duplicados del conector.

Descartar registros

Si un registro ya no es relevante (por ejemplo, el pedido fue cancelado o los datos fueron ingresados manualmente en el sistema destino), puedes descartarlo en lugar de reintentarlo.

• Descartar individual — haz clic en la fila y luego en Discard en el panel de detalles.
• Descartar seleccionados — marca varias filas y luego haz clic en Discard Selected (N) en la barra de herramientas.
• Descartar todos (o todos los filtrados) — haz clic en Discard All en el encabezado de la tabla. Esta acción requiere confirmación y es permanente.

Los registros descartados se eliminan de la lista de pendientes y su estado se establece como Discarded. Esta acción no puede deshacerse.

Qué pueden resolver los usuarios vs. qué escalar

Situación	Acción del usuario
Campo del mapeo faltante o incorrecto	Corrige la configuración de mapeo y luego reintenta.
El sistema destino no estaba disponible temporalmente	Espera a que el sistema se recupere y luego reintenta.
Las credenciales de autenticación cambiaron	Actualiza las credenciales del perfil de conexión y luego reintenta.
Registro rechazado por validación de datos	Corrige los datos fuente o el mapeo, luego reintenta con re-extracción.
Error desconocido sin causa clara	Inspecciona el payload completo; si no se puede resolver, contacta a soporte con el Correlation ID.
El volumen de registros es muy grande y el reintento es lento	Usa filtros de instancia y tipo de entidad para reintentar en lotes más pequeños.

Páginas relacionadas

• Historial de Ejecuciones — consulta el historial completo de ejecuciones completadas y sus resultados por entidad.
• Errores Comunes — referencia de patrones de error conocidos y sus soluciones.
• Depuración de Ejecuciones — guía paso a paso para diagnosticar una ejecución fallida.