Idempotência
Toda requisição que cria algo exige uma chave de idempotência. Repetir a chamada com a mesma chave devolve o recurso já criado em vez de criar outro.
Como usar
Envie o header Idempotency-Key com um valor de ao menos 8 caracteres, único por operação. O identificador do seu lado costuma ser a melhor escolha: o número do pedido, o id da fatura, o id do lote de repasse.
-H "Idempotency-Key: pedido-1042"Sem o header, a resposta é 400 com código IDEMPOTENCY_KEY_REQUIRED.
Escopo da chave
A chave é única por aplicação. Duas aplicações da mesma conta podem usar pedido-1042 sem colidir, e a mesma aplicação repetindo esse valor recebe de volta o mesmo recurso.
Por que isso importa
Timeout de rede não distingue "a requisição não chegou" de "a resposta se perdeu". Sem idempotência, o retry seguro vira cobrança duplicada ou, pior, transferência duplicada. Com ela, o retry é sempre seguro: basta repetir a chamada inteira, com a mesma chave.
Aplica-se a
POST /v1/charges e POST /v1/payouts. Rotas de leitura e a gestão de webhooks não pedem o header.