Idempotency-Key

A rede cai, o timeout estoura, o seu worker tenta de novo. Com a Idempotency-Key, repetir o mesmo pedido devolve a mesma resposta sem criar outra cobrança, outro pagamento ou outra devolução.

Onde é obrigatória

Rotas que exigem Idempotency-Key
RotaO que cria
POST /v1/chargesCriar cobrança
POST /v1/charges/:id/refundsCriar devolução (a cobrança entra na comparação)
POST /v1/payoutsCriar pagamento
POST /v1/payment-linksCriar link de pagamento
POST /v1/disputes/:id/evidenceEnviar evidência (compara a disputa, o sha256 e o tamanho do arquivo, o nome, a categoria e a descrição)

Sem o cabeçalho, essas rotas respondem 400 IDEMPOTENCY_KEY_REQUIRED. As outras rotas não usam a chave. Algumas já são seguras de repetir: cancelar uma cobrança já cancelada devolve a cancelada, mudar um link para o estado em que ele já está não muda nada, e salvar a mesma defesa ou explicação de MED não grava de novo.

Formato

  • De 1 a 255 caracteres visíveis (ASCII), sem espaços. Fora disso: 422 VALIDATION_ERROR.
  • Use um valor do seu sistema que identifique o pedido (o número do pedido, o id do repasse) ou um UUID gerado uma vez e guardado com ele.
  • A chave vale por empresa, ambiente e rota: a mesma chave em POST /v1/charges e em POST /v1/payouts são pedidos diferentes.

O que conta como o mesmo pedido

A API compara o corpo como JSON, sem ligar para a ordem dos campos. Mesmo corpo: volta a resposta guardada da primeira vez, com o mesmo status e o cabeçalho Idempotent-Replayed: true, e nada é criado de novo. Corpo diferente com a mesma chave: 409 IDEMPOTENCY_KEY_REUSED.

Resposta de erro 4xx também pode ficar guardada (as recusas de regra, como valor abaixo da tarifa ou saldo insuficiente, ficam). Corrigiu o corpo depois de um 4xx? Mande com uma chave nova. Resposta 5xx nunca fica: repetir com a mesma chave é seguro.

Ficam de fora, sem nada guardado: chave inválida ou sem escopo, e corpo fora do formato da rota (tipo errado ou campo desconhecido).

Erros

Códigos de erro
CódigoHTTPQuando acontece
IDEMPOTENCY_KEY_REQUIRED400Faltou o cabeçalho numa rota que exige.
IDEMPOTENCY_KEY_REUSED409A chave já foi usada nesta rota com outro corpo.
IDEMPOTENCY_REQUEST_IN_PROGRESS409O primeiro pedido com a chave ainda está rodando. Espere e repita; se ele morreu no meio, a chave é liberada depois de 2 minutos.
VALIDATION_ERROR422Chave com espaço, caractere fora do ASCII visível ou mais de 255 caracteres.

Validade

A resposta guardada vale por 7 dias. Depois disso, a mesma chave conta como nova. Para cobranças, o externalId é uma segunda proteção sem prazo: repetir o mesmo externalId com o mesmo conteúdo devolve a cobrança existente (veja Criar cobrança).