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
| Rota | O que cria |
|---|---|
POST /v1/charges | Criar cobrança |
POST /v1/charges/:id/refunds | Criar devolução (a cobrança entra na comparação) |
POST /v1/payouts | Criar pagamento |
POST /v1/payment-links | Criar link de pagamento |
POST /v1/disputes/:id/evidence | Enviar 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/chargese emPOST /v1/payoutssã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ódigo | HTTP | Quando acontece |
|---|---|---|
IDEMPOTENCY_KEY_REQUIRED | 400 | Faltou o cabeçalho numa rota que exige. |
IDEMPOTENCY_KEY_REUSED | 409 | A chave já foi usada nesta rota com outro corpo. |
IDEMPOTENCY_REQUEST_IN_PROGRESS | 409 | O primeiro pedido com a chave ainda está rodando. Espere e repita; se ele morreu no meio, a chave é liberada depois de 2 minutos. |
VALIDATION_ERROR | 422 | Chave 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).