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#
| Clase | Ejemplos | Qué pasa |
|---|---|---|
| retryable (transitoria/desconocida) | timeout, 5xx, error de red | reintenta 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éditos | va 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.:
[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)
- Ves
[tentativa N]y un horario[apos...]en la ejecución. - Espera: el dispatcher vuelve a ejecutar después del backoff, solo.
- 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)
- La ejecución aparece con status
dlqy sale de todos los filtros ejecutables. - Lee el motivo (el mensaje redactado dice qué pasó: permiso, sintaxis, créditos, etc.).
- Corrige la causa en la origen: credencial, permiso, SQL, saldo, configuración.
- 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:
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 DLQUn pipeline falló por un timeout de red:
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 DLQResultado 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 (
updateManycondicionado) 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íntoma | Causa probable | Qué hacer |
|---|---|---|
| Ejecución "atascada" en running | el proceso murió a la mitad | El "reaper" la recupera; la conciliación señala el hueco |
| Siempre vuelve a la DLQ | causa permanente no corregida | Corrige la origen (permiso/SQL/créditos) antes de reprocesar |
| Nunca reintenta | error clasificado como poison | Es 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#
- Programación, retry, DLQ y conciliación (referencia)
- Calidad, deduplicación y rechazados
- Crear validación de calidad
Última revisión: 2026-09-08.