Idempotency-Key. Sem ele, a
resposta é 422 missing_idempotency_key.
A regra
Uma chave representa uma operação lógica, não uma tentativa. Gere a chave uma vez, guarde no seu banco junto com o pedido e reutilize a mesma chave em todas as retentativas daquela operação.Certo
O cliente pediu a conta uma vez. Você gera uma chave, salva, e usa essa chave em
toda tentativa até obter uma resposta final.
Errado
Gerar uma chave nova a cada
fetch. Cada tentativa vira uma operação nova e
você pode criar dois clientes.Como o servidor trata a chave
A chave que você envia é combinada com a sua credencial e com a rota antes de ser armazenada. Duas consequências práticas:- A sua chave nunca colide com a de outro parceiro.
- A mesma chave usada em rotas diferentes são operações diferentes.
As três respostas possíveis
Primeira vez: a operação executa
Primeira vez: a operação executa
A chave é reservada, a operação roda e a resposta é gravada.
Retentativa depois de concluída: a resposta original volta
Retentativa depois de concluída: a resposta original volta
Mesma chave, mesmo corpo, operação já finalizada. Você recebe a mesma resposta
da primeira vez, sem novo efeito.
Retentativa com a primeira ainda rodando: 409 request_in_progress
Retentativa com a primeira ainda rodando: 409 request_in_progress
A tentativa anterior ainda está em andamento. Espere e tente de novo com a
mesma chave. Não troque a chave: o efeito pode já ter acontecido.
Conflito de corpo
Se você reutilizar a chave com um corpo diferente, a resposta é409 idempotency_conflict. O servidor compara o hash do corpo.
Isso protege contra o erro clássico: reaproveitar a chave de um pedido para outro
pedido. Corrija o corpo, ou gere uma chave nova se a operação realmente é outra.
A janela é de 24 horas
A chave vale por 24 horas. Depois disso, ela é descartada. Essa janela de 24 h é a de requisições. Ela não tem relação com a janela de deduplicação de 48 h dos webhooks, que existe porque a última retentativa de entrega chega cerca de 24,5 h depois da primeira.Padrão de implementação
Onde a chave é obrigatória
Rotas
GET não usam Idempotency-Key.