Idempotência

Rede cai no meio de um POST e você não sabe se a cobrança foi criada. Repetir sem cuidado cria duas. A Idempotency-Key resolve isso: a segunda chamada devolve a mesma resposta da primeira em vez de criar outro objeto.

Onde é obrigatória

Nas duas criações que movem dinheiro: cobrança e saque. Sem o header a resposta é 400 missing_idempotency_key.

GET não precisa (não cria nada) e o cancelamento de saque também não.

Como escolher a chave

O valor é seu. Formato aceito: de 1 a 255 caracteres em A-Z a-z 0-9 _ - : ..

Use algo derivado do seu domínio, não um valor aleatório novo a cada tentativa. A chave boa é a que a sua própria retentativa consegue reconstruir: pedido-A123-tentativa-1, saque-2026-09-17-001. Um UUID gerado no início do fluxo e guardado junto do pedido também serve. Um UUID gerado dentro do catch do retry não serve para nada.

O escopo é loja, ambiente e chave. A mesma Idempotency-Key em sk_test_ e em sk_live_ são duas chaves diferentes e nunca se confundem.

O que acontece ao repetir

Mesma chave, mesmo corpo, a primeira já terminou. Você recebe a resposta salva, com o status original e o header Idempotent-Replayed: true. Nada novo foi criado.

Mesma chave, corpo diferente. 409 idempotency_conflict. É proteção: se o valor mudou, é outro pedido e merece outra chave.

Mesma chave, a primeira ainda está rodando. 409 idempotency_in_progress. Espere alguns segundos e repita a mesma requisição. Uma tentativa que morreu no meio é liberada sozinha depois de 60 segundos e a próxima chamada assume o lugar dela.

Quando reusar a chave e quando trocar

A regra depende do que veio de volta:

• Erro de validação ou de negócio (400, 403, a maior parte dos 409). Nada foi criado e o registro da chave é apagado. Corrija o corpo e repita com a mesma chave.
• 201. Já criou. Repetir com a mesma chave devolve o mesmo objeto. Para criar outro, chave nova.
• 503 acquirer_timeout, acquirer_rejected ou acquirer_unavailable. Essa resposta fica gravada. Repetir com a mesma chave devolve o mesmo 503 para sempre. Para tentar de novo de verdade, use uma chave nova.

Esse último caso é o que mais pega gente. Um 503 quer dizer que o processador de pagamentos falhou e a cobrança ficou marcada como falha; a nova tentativa é um pedido novo, com chave nova.

Do outro lado: os seus webhooks

Idempotência na entrada da API é metade do trabalho. O seu receptor de webhook também precisa deduplicar, porque um mesmo evento pode chegar duas vezes. Isso está em Idempotência e ordem.

Próximo passo

Erros mostra o envelope que toda falha usa e o que fazer com cada classe de código.

Referência: Cria uma cobrança PIX e Solicita um saque (exige o header Idempotency-Key) são as duas operações que exigem o header.