Pular para o conteúdo principal

Idempotency

Toda operação financeiramente relevante que muda estado aceita uma idempotency key. Enviar a mesma key com o mesmo payload é sempre seguro — retorna o resultado original em vez de executar de novo. Enviar a mesma key com um payload diferente é rejeitado com IDEMPOTENCY_KEY_CONFLICT (409, ver Errors § Conflitos de idempotência) — nunca sobrescreve ou executa em dobro silenciosamente.

Onde a key vai​

Existem dois mecanismos reais, e qual deles se aplica depende da rota específica:

  • Campo do corpo (o caso comum) — um parâmetro opcional idempotencyKey em operações como criar uma Transaction, um PaymentIntent, executar um Settlement ou um Refund, solicitar um Withdrawal, ou ingerir um Event.
  • Header Idempotency-Key — usado só por duas rotas: criar uma Organization e criar uma Application. Se você está chamando diretamente via HTTP em vez de por um SDK, confira qual mecanismo a página de API Reference da operação específica documenta.

Se você omitir a key, cada SDK oficial gera um UUID v4 aleatório automaticamente — o que significa que uma chamada de SDK sem key explícita não é idempotente entre chamadas separadas (cada uma gera sua própria key). Sempre passe uma key explícita e determinística quando você efetivamente precisa de segurança contra replay (ex.: derivada do seu próprio ID de pedido ou de um request ID que você controla) — o padrão auto-gerado só protege os retries internos de uma única chamada, nunca duas chamadas independentes que deveriam ter sido "a mesma" operação.

Comportamento de retry​

A própria lógica de retry automático de um SDK (falhas de rede, 5xx, rate limiting) sempre reaproveita a mesma key da primeira tentativa — nunca gera uma key nova por tentativa. É isso que torna os retries automáticos seguros por padrão: uma chamada reenviada que na verdade já teve sucesso no servidor numa tentativa anterior repete esse mesmo resultado em vez de executar uma segunda vez.

O que "mesmo payload" significa​

A plataforma compara o payload associado a uma key já usada com o payload da nova requisição. Se baterem, você recebe o resultado original de volta (replay, não uma execução nova — sem efeito financeiro duplicado). Se diferirem em qualquer campo que a plataforma considere significativo, você recebe IDEMPOTENCY_KEY_CONFLICT. Nunca reutilize uma key entre duas operações conceitualmente diferentes, mesmo que espere que o conflito seja inofensivo — trate uma key como uma identidade única para uma operação específica pretendida.

Exemplo​

// Key determinística derivada do seu próprio ID de pedido -- seguro para tentar de novo essa
// chamada exata quantas vezes for preciso; nunca derivada de Date.now()/Math.random(), o que
// anularia todo o mecanismo.
const idempotencyKey = `settle-order-${orderId}`;

const settlement = await client.settlements.executeSettlement(transactionId, undefined, idempotencyKey);