Dead Letter Queue no Node.js: trate falhas em filas

Dead Letter Queue no Node.js é um destino para mensagens que não puderam ser processadas após tentativas controladas ou que possuem erro permanente. A DLQ impede que uma mensagem inválida bloqueie indefinidamente a fila principal.

Ela não é uma lixeira automática. Uma operação madura precisa classificar erros, preservar contexto, alertar responsáveis e oferecer reprocessamento seguro.

Quando enviar para DLQ?

• schema inválido;
• referência de negócio inexistente e não recuperável;
• tentativas transitórias esgotadas;
• evento incompatível;
• falha de autorização permanente;
• bug que exige correção antes do replay.

Erro transitório ou permanente

export function classificarErro(error) {
  if (error.code === 'ETIMEDOUT') return 'transient';
  if (error.code === 'ECONNRESET') return 'transient';
  if (error.code === 'INVALID_SCHEMA') return 'permanent';
  if (error.code === 'NOT_AUTHORIZED') return 'permanent';
  return 'unknown';
}

Erros desconhecidos podem receber poucas tentativas antes de ir para análise.

Envelope da DLQ

{
  "failedMessage": { "id": "evt-1", "type": "order.created.v1" },
  "failure": {
    "code": "INVALID_SCHEMA",
    "message": "Campo totalCents ausente",
    "attempts": 4,
    "failedAt": "2026-10-16T16:00:00Z"
  },
  "source": {
    "topic": "orders.events",
    "partition": 3,
    "offset": "992"
  }
}

Não copie stack completa com segredos. Preserve o payload necessário de forma protegida.

Retry antes da DLQ

Use backoff exponencial e jitter para falhas transitórias. O número de tentativas deve depender do SLA e do tipo de dependência.

function delay(attempt) {
  return Math.min(300000, 1000 * 2 ** attempt) * (0.5 + Math.random());
}

RabbitMQ

Configure dead-letter exchange na fila principal e filas de retry com TTL. Quando as tentativas terminarem, publique na fila final de erro.

Kafka

Use um tópico como orders.events.dlq. Inclua tópico, partição e offset de origem. A publicação na DLQ e o avanço do offset precisam ser coordenados com cuidado.

Idempotência no replay

Uma mensagem reprocessada pode ter sido aplicada parcialmente. O consumidor deve registrar o ID e executar efeitos de forma idempotente.

Reprocessamento

Um fluxo seguro deve permitir:

1. filtrar mensagens por erro e período;
2. corrigir configuração ou código;
3. validar payload;
4. republicar com novo ID de tentativa e referência ao original;
5. acompanhar resultado;
6. evitar replay em massa sem limite.

Poison message

Uma poison message sempre falha. Recolocá-la automaticamente na fila principal cria loop. Envie para DLQ após limite e exija correção.

Parking Lot Queue

Algumas arquiteturas usam uma fila de estacionamento para mensagens que aguardam ação externa, diferente da DLQ de falha definitiva. Isso facilita separar incidentes operacionais de dependências de negócio.

Observabilidade

Monitore quantidade na DLQ, taxa de entrada, idade da mensagem mais antiga, erros por código, origem e sucesso de replays.

Crie alertas diferentes para crescimento rápido e mensagens antigas sem tratamento.

Dashboard operacional

Exiba ID, tipo, aggregate, tentativas, erro, horário e origem. O acesso deve ser restrito porque payloads podem conter dados sensíveis.

Retenção

Defina período de retenção e arquivamento. Não mantenha mensagens indefinidamente. Regras de privacidade também se aplicam à DLQ.

Testes

• erro transitório gera retry;
• erro permanente vai direto para DLQ;
• tentativas são limitadas;
• payload mantém metadados;
• replay é idempotente;
• mensagem corrigida volta ao fluxo;
• alertas são disparados.

Segurança

Redija tokens, senhas e dados pessoais. Use ACL específica para leitura e replay. Registre quem reprocessou e qual filtro foi usado.

Erros comuns

• DLQ sem alerta;
• retry infinito;
• reprocessamento manual sem auditoria;
• payload sem origem;
• stack com segredo;
• replay não idempotente;
• mesma retenção para todos os dados;
• tratar qualquer erro como transitório.

Conclusão

Dead Letter Queue no Node.js isola mensagens problemáticas e mantém o fluxo principal saudável. O valor aparece quando há classificação, alertas, retenção e procedimento de replay.

Combine DLQ com consumidores idempotentes, retries limitados e observabilidade. Leia RabbitMQ no Node.js e Kafka no Node.js.

Consulte a documentação de dead-letter exchanges do RabbitMQ e a documentação do Apache Kafka.