Skip to content
Docs

This page has not been translated yet — you are reading the Portuguese version. View in Portuguese

GA candidateUpdated on 2026-09-08

Tutorial — tratar falhas e a DLQ (Dead Letter Queue)

Passo a passo para entender retry com backoff, falhas permanentes na DLQ e como reprocessar de forma auditada.

On this page (17)

Estado: Preview. As regras de retry/backoff, DLQ e reconciliação são provadas por teste determinístico (esta capacidade = GA-candidato); a execução real em fila de nuvem = NÃO MEDIDO. Exemplos sintéticos.

Leia antes: Agendamento, retry, DLQ e reconciliação.

O que é#

Nem toda execução termina bem. O Ingestia trata falhas em três níveis: re-tenta o que é transiente (com backoff), isola o que é permanente numa DLQ (Dead Letter Queue), e diagnostica buracos entre camadas após uma interrupção. Este tutorial mostra como ler e agir sobre cada um.

A DLQ é para execuções (jobs) que falham — não para linhas de dado. Linhas reprovadas na qualidade são outra coisa (veja Qualidade).

Para que serve#

Evitar que uma falha temporária derrube o fluxo (retry resolve sozinho) e garantir que uma falha permanente não fique em loop consumindo recurso (vai para a DLQ e espera uma pessoa).

Quando usar / quando não usar#

  • Use este guia quando um refresh/report/pipeline falhar ou aparecer na DLQ.
  • Não reprocesse cegamente uma falha permanente sem corrigir a causa — ela voltará para a DLQ.

Plano e permissões#

  • Núcleo · verificação de acesso · chaves de desligamento para execução de ingestão, execução de relatórios, atualização de painéis.
  • Reprocessar a partir da DLQ é uma ação manual de operador, auditada.

Como o Ingestia classifica a falha#

ClasseExemplosO que acontece
retryable (transiente/desconhecida)timeout, 5xx, erro de redere-tenta com backoff até o teto
poison (config/validação — retry não conserta)not found, syntax error, access denied, invalid_grant, sem saldo de créditosvai direto para a DLQ, sem queimar tentativas

Retry com backoff (o que você vê)#

  • Teto de tentativas por tipo: dashboard 2 · report 3 · pipeline 2.
  • Backoff exponencial base × 2^(n-1) com jitter determinístico; base 5 min (1 tick do cron), teto 1 h, jitter até 25%.
  • O estado de retry aparece em marcadores no campo de erro, ex.:
code
[tentativa 2] [apos 2026-09-08T13:40:00Z] connection reset by peer

[tentativa N] = quantas vezes já re-tentou; [apos <ISO>] = "não execute antes de".

Passo a passo#

Caso 1 — falha transiente (o retry resolve)

  1. Você vê [tentativa N] e um horário [apos...] no run.
  2. Aguarde: o dispatcher re-executa após o backoff, sozinho.
  3. Se voltar ao normal, nada a fazer. Se estourar o teto, vira DLQ (caso 2).

Caso 2 — falha permanente (DLQ)

  1. O run aparece com status dlq e sai de todos os filtros executáveis.
  2. Leia o motivo (a mensagem redigida diz o que aconteceu: permissão, sintaxe, crédito, etc.).
  3. Corrija a causa na origem: credencial, permissão, SQL, saldo, configuração.
  4. Reprocesse manualmente a partir da DLQ (ação de operador, com auditoria). Nunca é automático.

Caso 3 — interrupção no meio (reconciliação)

Um kill no meio pode deixar buraco entre camadas (Bronze sem Silver, Gold anterior à Silver). O Ingestia compara os três rastros (execução, Bronze, transformações) e produz um relatório acionável por workspace. A correção fica com o operador (sem correção automática hoje).

Exemplo (sintético)#

Um refresh de dashboard falhou por token expirado do conector:

code
Erro: [tentativa 1] invalid_grant: token expired
Classe: poison (invalid_grant) → DLQ direto
Ação: renovar a credencial da fonte → reprocessar a partir da DLQ

Um pipeline falhou por timeout de rede:

code
Erro: [tentativa 1] [apos 2026-09-08T13:35:00Z] ETIMEDOUT
Classe: retryable → re-tenta em ~5 min (backoff)
Ação: aguardar; se estourar o teto (2), vira DLQ

Resultado esperado#

  • Falhas transientes se resolvem sozinhas dentro do teto de tentativas.
  • Falhas permanentes ficam paradas na DLQ (não queimam recurso) até correção + reprocessamento auditado.
  • Após uma interrupção, o relatório de reconciliação aponta exatamente onde ficou o buraco.

Limites e custos#

  • Tentativas: dashboard 2 / report 3 / pipeline 2. Backoff base 5 min, teto 1 h.
  • O retry com backoff reduz custo de re-execução cega; o jitter evita "martelar" a fonte. Custo faturado em BRL = NÃO MEDIDO.

Segurança#

  • Claim atômico (updateMany condicionado) evita que dois dispatchers peguem o mesmo run.
  • A DLQ exige intervenção humana auditada para reprocessar.
  • A reconciliação é read-only e escopada por workspaceId — o carimbo de um cliente nunca lê o de outro. Mensagens de erro têm segredos redigidos.

Erros comuns#

SintomaCausa provávelO que fazer
Run "preso" em runningprocesso morreu no meioO "reaper" recupera; a reconciliação aponta o buraco
Volta sempre para a DLQcausa permanente não corrigidaCorrija a origem (permissão/SQL/crédito) antes de reprocessar
Nunca re-tentaerro classificado como poisonÉ esperado: poison vai direto à DLQ

Diagnóstico#

  • Leia os marcadores [tentativa N]/[apos...] para entender em que ponto do retry o run está.
  • Use o relatório de reconciliação após qualquer interrupção.
  • Cheque a observabilidade do conector (taxa de erro ≥ 20% → degradado; freshness > 26 h → degradado, > 72 h → parado).

Relacionados#

Última revisão: 2026-09-08.

Related links