Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-09-08

Tutorial — manejar fallas y la DLQ (Dead Letter Queue)

Paso a paso para entender el retry con backoff, las fallas permanentes en la DLQ y cómo reprocesar de forma auditada.

En esta página (17)

Lee antes: Programación, retry, DLQ y conciliación.


Qué es#

No toda ejecución termina bien. Ingestia maneja las fallas en tres niveles: reintenta lo que es transitorio (con backoff), aísla lo que es permanente en una DLQ (Dead Letter Queue) y señala huecos entre capas después de una interrupción. Este tutorial muestra cómo leer y actuar sobre cada uno.

La DLQ es para ejecuciones (jobs) que fallan — no para filas de datos. Las filas rechazadas por calidad son otra cosa (ver Calidad).

Para qué sirve#

Evitar que una falla temporal tumbe el flujo (el retry la resuelve solo) y garantizar que una falla permanente no quede en un bucle consumiendo recursos (va a la DLQ y espera a una persona).

Cuándo usar / cuándo no usar#

  • Usa esta guía cuando un refresh/report/pipeline falle o aparezca en la DLQ.
  • No reproceses a ciegas una falla permanente sin corregir la causa — volverá a la DLQ.

Plan y permisos#

  • Núcleo · verificación de acceso · interruptores de apagado para ejecución de ingesta, ejecución de informes y actualización de paneles.
  • Reprocesar desde la DLQ es una acción manual de operador, auditada: no hay botón en la pantalla; pídelo por Aiô o abre un ticket. Para ejecutarlo de nuevo tú mismo, usa Ejecuciones › Recuperar… › Ejecutar el pipeline de nuevo.

Cómo clasifica Ingestia la falla#

ClaseEjemplosQué pasa
retryable (transitoria/desconocida)timeout, 5xx, error de redreintenta con backoff hasta el tope
poison (configuración/validación — el retry no lo arregla)not found, syntax error, access denied, invalid_grant, sem saldo de créditosva directo a la DLQ, sin gastar intentos

Retry con backoff (lo que ves)#

  • Tope de intentos por tipo: dashboard 2 · report 3 · pipeline 2.
  • Backoff exponencial base × 2^(n-1) con jitter determinista; base 5 min (1 tick del cron), tope 1 h, jitter de hasta 25%.
  • El estado del retry aparece como marcadores en el campo de error, ej.:
código
[tentativa 2] [apos 2026-09-08T13:40:00Z] connection reset by peer

[tentativa N] = cuántas veces ya reintentó; [apos <ISO>] = "no ejecutar antes de".

Paso a paso#

Caso 1 — falla transitoria (el retry la resuelve)

  1. Ves [tentativa N] y un horario [apos...] en la ejecución.
  2. Espera: el dispatcher vuelve a ejecutar después del backoff, solo.
  3. Si vuelve a la normalidad, no hay nada que hacer. Si supera el tope, pasa a la DLQ (caso 2).

Caso 2 — falla permanente (DLQ)

  1. La ejecución aparece con status dlq y sale de todos los filtros ejecutables.
  2. Lee el motivo (el mensaje redactado dice qué pasó: permiso, sintaxis, créditos, etc.).
  3. Corrige la causa en la origen: credencial, permiso, SQL, saldo, configuración.
  4. Reprocesa: pide al soporte (por Aiô o por ticket) el reproceso desde la DLQ (acción de operador, con auditoría, nunca automática) o ejecútalo de nuevo por la pantalla en Ejecuciones › Recuperar… › Ejecutar el pipeline de nuevo.

Caso 3 — interrupción a la mitad (conciliación)

Un kill a la mitad puede dejar un hueco entre capas (Bronze sin Silver, Gold anterior a Silver). Ingestia compara los tres rastros (ejecución, Bronze, transformaciones) y produce un informe accionable por workspace. La corrección queda a cargo del operador (sin corrección automática hoy).

Ejemplo (sintético)#

Un refresh de dashboard falló por un token vencido del conector:

código
Error: [tentativa 1] invalid_grant: token expired
Clase: poison (invalid_grant) → directo a la DLQ
Acción: renovar la credencial de la fuente → reprocesar desde la DLQ

Un pipeline falló por un timeout de red:

código
Error: [tentativa 1] [apos 2026-09-08T13:35:00Z] ETIMEDOUT
Clase: retryable → reintenta en ~5 min (backoff)
Acción: esperar; si supera el tope (2), pasa a la DLQ

Resultado esperado#

  • Las fallas transitorias se resuelven solas dentro del tope de intentos.
  • Las fallas permanentes quedan detenidas en la DLQ (no gastan recursos) hasta la corrección + el reprocesamiento auditado.
  • Después de una interrupción, el informe de conciliación señala exactamente dónde quedó el hueco.

Límites y costos#

  • Intentos: dashboard 2 / report 3 / pipeline 2. Backoff base 5 min, tope 1 h.
  • El retry con backoff reduce el costo de reejecutar a ciegas; el jitter evita "martillar" la fuente.

Seguridad#

  • El claim atómico (updateMany condicionado) evita que dos dispatchers tomen la misma ejecución.
  • La DLQ exige intervención humana auditada para reprocesar.
  • La conciliación es de solo lectura y está acotada por workspaceId — la marca de un cliente nunca lee la de otro. Los mensajes de error tienen los secretos redactados.

Errores comunes#

SíntomaCausa probableQué hacer
Ejecución "atascada" en runningel proceso murió a la mitadEl "reaper" la recupera; la conciliación señala el hueco
Siempre vuelve a la DLQcausa permanente no corregidaCorrige la origen (permiso/SQL/créditos) antes de reprocesar
Nunca reintentaerror clasificado como poisonEs lo esperado: poison va directo a la DLQ

Solución de problemas#

  • Lee los marcadores [tentativa N]/[apos...] para entender en qué punto del retry está la ejecución.
  • Usa el informe de conciliación después de cualquier interrupción.
  • Revisa la observabilidad del conector (tasa de error ≥ 20% → degradado; freshness > 26 h → degradado, > 72 h → detenido).

Relacionados#


Última revisión: 2026-09-08.

Enlaces relacionados