1) Tratar evento como “chamada de função assíncrona”

Um dos maiores desvios em sistemas event-driven é pensar que “publicar um evento” equivale a “executar imediatamente” um comportamento em outro lugar.
Na prática, você está em um ambiente com latência, duplicação, reentrega e, às vezes, entrega fora de ordem.

• Erro comum: lógica que assume tempo real (“agora já processou”) e falta de compensação.
• Erro comum: consumidor que atualiza estado sem checar versão, consistência e causalidade.
• O que fazer: modelar o domínio como um conjunto de transições de estado e aceitar que eventos são “registros de fatos”, não sincronização.

2) Não projetar idempotência (e sofrer com duplicatas)

Em event-driven, duplicatas são inevitáveis: reentrega por timeout, falha parcial, commit fora de ordem, ou estratégias de retry.
Sem idempotência, você cria efeitos colaterais duplicados (duplo débito, dupla criação, contagem errada).

• Erro comum: consumidores que assumem “cada evento chega uma vez”.
• Erro comum: usar “eventId” apenas em logs, mas não como chave de deduplicação.
• O que fazer: registre o processamento por chave do evento e aplique “efeito uma vez” (at-least-once + idempotência).

// Exemplo (conceitual) de idempotência em um consumidor.
// Ideia: persistir o eventId (ou combinação chave) antes/depois da ação,
// e ignorar eventos já processados.

async function onEvent(event) {
  const key = event.eventId; // chave única do evento (contrato)

  // 1) Deduplicação
  const already = await db.processedEvents.findById(key);
  if (already) return;

  // 2) Execução do efeito colateral (transação)
  await db.transaction(async (tx) => {
    // Recheca em transação para evitar corrida
    const again = await tx.processedEvents.findById(key);
    if (again) return;

    await tx.applyDomainEffect(event); // ex: criar faturamento
    await tx.processedEvents.insert({ id: key, processedAt: new Date() });
  });
}
        

3) Ignorar versionamento e evolução do contrato

Um evento é um contrato entre produtores e consumidores. Quando você muda o payload sem estratégia,
consumidores antigos quebram silenciosamente ou passam a interpretar dados de forma incorreta.

• Erro comum: renomear campos, mudar tipos ou remover propriedades sem versionar.
• Erro comum: publicar payload “livre” (sem schema), forçando adivinhação no consumidor.
• Erro comum: assumir que todos consumidores serão atualizados no mesmo instante.
• O que fazer: usar versionamento explícito do evento e regras de compatibilidade:
  • campos novos: adiciona mantendo compatibilidade;
  • campos alterados: cria nova versão (ex: v2);
  • remover: só após a migração completa.

4) Falhar em observabilidade e tratamento de falhas (o sistema “fica preto”)

Event-driven costuma falhar de forma distribuída: mensagens paradas, consumidores indisponíveis, retries em loop, filas crescendo.
Se não houver telemetria e estratégia de erro, você só descobre quando o negócio já foi impactado.

• Erro comum: logs sem correlação (rastrear “por que não processou” vira um caos).
• Erro comum: retry sem limite e sem classificar erro (ex: retry para dados inválidos).
• Erro comum: não ter “dead letter queue”/quarentena para mensagens problemáticas.
• Erro comum: não monitorar lag de consumidor, taxa de erro e tempo de processamento.

Fechando: um “modelo mental” para reduzir erros

Se eu tivesse que resumir em uma regra operacional, seria:
event-driven bem-sucedido trata mensagens como entrega “não garantida” e estado como “convergência”.

• Confiabilidade: idempotência e tolerância a duplicatas.
• Contratos: versionamento e compatibilidade do payload.
• Fluxo: causalidade explícita no domínio (e não no tempo).
• Operação: observabilidade e políticas de erro.