Nesta página
Uma chave para a mesma intenção
Envie Idempotency-Key ao criar uma transação. O header é opcional no contrato, mas é recomendado para tolerar uma conexão perdida depois que o servidor recebeu seu pedido. Gere e persista a chave antes do primeiro POST; reutilize-a somente para a mesma criação e o mesmo payload.
Idempotency-Key: onboarding-demo-0001Resposta perdida não significa criação perdida
Imagine que seu servidor envia o pedido e recebe um timeout. A transação pode ter sido criada. Repetir com uma chave nova pode criar uma segunda jornada. Repetir o mesmo POST com a mesma chave e payload permite recuperar a criação idempotente; o retorno documentado continua sendo 201.
Use external_id para correlação de negócio, sem tratá-lo como substituto automático do header. Mantenha a associação entre chave, tentativa e transação no seu sistema.
Trate o conflito explicitamente
A mesma chave com payload diferente resulta em 409 com código idempotency_conflict. Não contorne esse retorno trocando a chave silenciosamente. Descubra se o cliente alterou os dados ou se sua aplicação reconstruiu a requisição de forma inconsistente.
Uma intenção realmente nova recebe uma chave nova. Uma repetição técnica preserva a intenção anterior. Não presuma uma janela de retenção da chave que não esteja documentada para seu contrato.
A idempotência da criação não substitui a deduplicação de webhooks. Para eventos, use event_id e mantenha efeitos de negócio também idempotentes.