Como evitar enviar o mesmo SMS duas vezes?

Uma conexão pode cair depois que Bird aceita um SMS, mas antes de sua aplicação receber a resposta. Tentar novamente com uma nova chave pode criar um segundo envio porque Bird trata isso como uma solicitação separada.

Como a chave funciona?

Você define um cabeçalho Idempotency-Key para cada envio SMS pretendido e o reutiliza ao tentar novamente a solicitação idêntica. Quando Bird retém a resposta original, uma nova tentativa correspondente retorna essa resposta sem executar o envio novamente.

Por exemplo, uma confirmação de pedido mantém a mesma chave ao longo de um timeout e sua nova tentativa. Uma confirmação de um pedido diferente recebe uma chave diferente.

Respostas reproduzidas incluem Idempotency-Replay: true, o que permite que seus logs distingam um replay de uma solicitação recém-processada.

Chaves SMS são vinculadas ao seu espaço de trabalho. Bird retém respostas completas por três horas conforme seu contrato de idempotência. Após essa janela, a mesma chave pode executar uma nova solicitação porque seu registro de replay expirou. Uma nova tentativa um dia depois, portanto, exige reconciliação do resultado original antes de outro envio.

O que as respostas de falha estão dizendo?

O código de erro distingue uma solicitação alterada, uma solicitação não finalizada e proteção indisponível.

• 409 com E01005 IdempotencyKeyReuse: a mesma chave foi usada para uma solicitação diferente. Corrija a atribuição da chave antes de tentar novamente, pois esta chave pertence à solicitação original. Bird compara o método, endpoint, path e parâmetros de query, e o corpo bruto. Até uma alteração nos espaços em branco do JSON torna a solicitação diferente.
• 409 com E01004 RequestInProgress: uma solicitação concorrente com a mesma chave não foi finalizada. Aguarde brevemente e tente novamente com a mesma chave e solicitação para que a original possa ser concluída. O bloqueio da solicitação em andamento expira em até 30 segundos. A expiração não estabelece se o envio original foi efetivado.
• 503 com E01033 IdempotencyUnavailable: a proteção estava indisponível antes da execução, portanto esta tentativa não foi executada. Tente novamente com backoff usando a mesma chave e solicitação. Esta resposta não estabelece o resultado de uma tentativa anterior.
• Outras respostas 5xx ou timeouts: tente novamente com backoff usando a mesma chave e solicitação. Bird não retém respostas 5xx. Uma nova tentativa reproduz uma resposta bem-sucedida retida ou pode executar novamente se nenhuma resposta foi retida.

O cabeçalho de idempotência preserva a identidade da solicitação ao longo dessas novas tentativas.

A chave garante zero duplicatas?

A chave reduz envios duplicados, mas não garante uma única execução.

Um envio pode ser efetivado antes que Bird retenha sua resposta. Se a retenção da resposta falhar ou o bloqueio da solicitação em andamento expirar, uma nova tentativa pode executar o envio novamente. A janela de retenção de três horas também limita a proteção de replay.

Mantenha os registros de eventos e envios da sua aplicação para que você possa reconciliar um resultado incerto antes de enviar novamente. Inclua o número do pedido ou referência na mensagem para que o destinatário reconheça a qual evento ela se refere.

E uma mensagem que o celular exibe duas vezes?

Uma chave de idempotência controla novas tentativas API; ela não controla como o telefone do destinatário exibe uma mensagem. Uma captura de tela sozinha não estabelece onde uma duplicação se originou.

Compare o log completo de envios da aplicação com os registros de mensagens de Bird. Múltiplos IDs de mensagem aceitos podem comprovar múltiplos envios. Encontrar apenas um ID em um log incompleto não prova que a duplicação aconteceu nas etapas seguintes. Inclua os IDs relevantes, destino e timestamps ao solicitar ao suporte que investigue.

O que devo fazer?

1. Atribua uma chave a cada envio SMS pretendido e reutilize a solicitação idêntica para suas novas tentativas.
2. Tente novamente em caso de erros de rede, timeouts e respostas 5xx com backoff, preservando a chave para manter qualquer proteção de replay disponível.
3. Corrija conflitos de solicitação alterada e atrase novas tentativas quando a solicitação original ainda estiver em andamento.
4. Reconcilie envios incertos, incluindo aqueles além da janela de replay de três horas, antes de decidir se outro envio é apropriado.