Toda operação que altera estado exige o header 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.
A reserva acontece antes de qualquer criação de conta ou chamada ao provedor. Duas requisições simultâneas com a mesma chave nunca produzem dois efeitos.

As três respostas possíveis

A chave é reservada, a operação roda e a resposta é gravada.
Mesma chave, mesmo corpo, operação já finalizada. Você recebe a mesma resposta da primeira vez, sem novo efeito.
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.
Uma retentativa de abertura de conta depois de 24 h não repete a resposta original. Ela é barrada pela verificação de identidade e responde 409 cpf_already_registered ou 409 cnpj_already_registered. Nenhuma segunda conta é criada, mas você também não recupera o accountId por essa via: consulte com GET /v1/accounts.
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.