## 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.

```http
Idempotency-Key: onboarding-demo-0001
```

## Resposta 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](/pt-BR/desenvolvedores/kyc/webhooks-e-eventos). Para eventos, use `event_id` e mantenha efeitos de negócio também idempotentes.