Contenha primeiro
- Pause a rotina ou fila responsável, se possível
- Levante quem recebeu em dobro e, em cobranças, estorne ou cancele as duplicadas
- Comunique os clientes afetados
Causas comuns
| Causa | Como acontece |
|---|---|
| Fila com tempo mal configurado | A tarefa demora mais que o tempo de liberação e outro worker a executa de novo |
| Nova tentativa após falha parcial | A mensagem foi enviada, mas a tarefa falhou depois e foi repetida |
| Agendador em vários servidores | A mesma rotina roda em cada máquina |
| Webhook repetido | O mesmo evento processado duas vezes (detalhes) |
| Clique duplo | Botão de enviar ou cobrar acionado duas vezes |
Como prevenir
- Registrar cada envio e cobrança com uma chave única (cliente + referência + período) e verificar antes de executar
- Usar chaves de idempotência nos gateways que oferecem esse recurso
- Configurar o tempo de liberação da fila maior que a duração das tarefas
- Rodar rotinas agendadas em um único servidor ou com trava compartilhada
- Separar a etapa de envio do restante da tarefa, para que uma falha posterior não repita o envio
Leia também
Veja filas do Laravel não processam, que explica o tempo de liberação, e registros duplicados. Corrigimos duplicidades em envios e cobranças no nosso serviço de manutenção de sistemas PHP e Laravel.