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?

Defina um cabeçalho Idempotency-Key para cada envio SMS pretendido e reutilize-o ao tentar novamente a solicitação idêntica. A garantia de aceitação exatamente uma vez significa que novas tentativas correspondentes dentro de três horas devem resultar no mesmo envio aceito, mesmo que você tenha perdido a resposta.

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.
• 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. A garantia de aceitação exatamente uma vez cobre essas novas tentativas dentro de três horas. Pare quando seu limite de novas tentativas se esgotar.

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

A chave garante zero duplicatas?

A garantia é a aceitação exatamente uma vez de solicitações idênticas com a mesma chave, no mesmo espaço de trabalho, dentro de três horas. Essas novas tentativas devem resultar em um único envio aceito, inclusive após uma resposta perdida. Verifique o status da mensagem para confirmar a entrega.

Após a janela de retenção de três horas, a chave original pode identificar uma nova operação. Se o resultado original for desconhecido, reconcilie-o antes de enviar novamente.

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 com backoff em caso de erros de rede, timeouts e respostas 5xx, preservando a chave e a solicitação idêntica dentro de três horas.
3. Corrija conflitos de solicitação alterada e atrase novas tentativas quando a solicitação original ainda estiver em andamento.
4. Mantenha pendentes as novas tentativas esgotadas ou expiradas até reconciliar o resultado delas, antes de decidir se outro envio é apropriado.