Idempotência

Uma chave por intenção de envio#

Gere uma chave para cada novo pedido de código, guarde-a com o corpo serializado e reutilize ambos nas retentativas desse pedido.

Idempotency-Key: login-unique-attempt-001

A chave é opcional, pertence à aplicação e tem no máximo 255 bytes após remover espaços nas extremidades. Uma chave vazia equivale a não usar idempotência. Prefira ASCII, como um UUID.

Duas aplicações podem usar a mesma chave sem compartilhar o envio. Na mesma aplicação, a mesma chave e o mesmo corpo retornam o mesmo id, sem reservar outra unidade nem consumir novamente o limite de criação.

O corpo precisa ser idêntico#

A API calcula o hash dos bytes exatos recebidos. JSON com os mesmos valores pode ter outro hash se você mudar espaços, ordem dos campos ou a representação do texto.

{"to":"+5531999999999","locale":"pt-BR"}

{ "locale": "pt-BR", "to": "+5531999999999" }

Serialize o corpo uma vez e reutilize a string ou o buffer. Em clientes Python, PHP e JavaScript, não reconstrua o objeto com outra ordem de campos ao retentar.

Retentativa no servidor#

const key = crypto.randomUUID();
const body = JSON.stringify({ to: "+5531999999999", locale: "pt-BR" });

async function requestSend() {
  return fetch("https://api.aut2fa.com/v1/send", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.AUT2FA_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body,
  });
}

// Guarde key e body para repetir este pedido após uma falha de rede.
const response = await requestSend();

Uma resposta HTTP recebida deve ser tratada antes da retentativa. Em 429, respeite Retry-After. Em falha temporária de rede ou servidor, repita com intervalo crescente e um número limitado de tentativas.

Conflito e reenvio#

409 com idempotency_key_reused significa que a chave já existe com outro corpo. Recupere o corpo original para retentar a mesma operação.

Para um novo pedido de código, inclusive depois de expiração ou bloqueio, gere outra chave. Reutilizar a chave antiga recupera o envio antigo, sem renovar o prazo ou reiniciar tentativas.

O cabeçalho vale para POST /v1/send. A verificação é de uso único e não implementa essa idempotência.