Idempotência
O header Idempotency-Key faz a API de pagamentos devolver a resposta original quando o mesmo pedido de cobrança é repetido, sem criar outra cobrança.
Idempotência é a propriedade de um pedido que pode ser repetido sem mudar o resultado. Na API de pagamentos, toda criação de cobrança exige o header Idempotency-Key. Quando a rede falha e o seu sistema repete o pedido com a mesma chave, a API devolve a resposta do primeiro pedido e não cria uma segunda cobrança.
Idempotency-Key: pedido-1234O valor tem de 1 a 255 caracteres ASCII imprimíveis.
Como a API responde
| Situação | Resposta |
|---|---|
| Mesma chave e mesmo corpo | A resposta original, com o mesmo status. Nenhuma cobrança nova é criada, e a resposta traz o header Idempotent-Replayed: true. |
| Mesma chave e corpo diferente | Erro 409 idempotency_key_reused. A comparação é byte a byte, então o corpo reenviado precisa ser idêntico, sem reformatar o JSON. Essa trava continua depois das 24 horas. |
| Mesma chave com o primeiro pedido ainda em andamento | Erro 409 request_in_progress. O pedido pode ser repetido em instantes. |
A resposta original fica guardada por 24 horas.
O valor da chave
A chave identifica o pedido no seu sistema, como o número do pedido ou um UUID gerado uma vez por compra. Um valor novo a cada tentativa é tratado como um pedido novo e cria uma cobrança nova.
Quando o pedido é repetido com a mesma chave
A documentação da API indica repetir o pedido com a mesma Idempotency-Key quando a resposta é 500 internal_error ou 502 gateway_unavailable, e quando a conexão cai sem resposta. No 502, a API consulta a cobrança antes de tentar de novo, então a cobrança não é duplicada.
O cancelamento não precisa de Idempotency-Key: cancelar duas vezes tem o mesmo resultado.
A referência do pedido
O campo external_reference também é único na conta. Mesmo com outra Idempotency-Key, a mesma referência não gera uma segunda cobrança enquanto a primeira estiver aberta ou paga, e a API responde 409 external_reference_taken. Quando a primeira cobrança vence, falha ou é cancelada, a referência fica livre de novo.
Páginas relacionadas
- Primeira cobrança Pix: a requisição de criação com o header.
- Erros e limites: todos os códigos de erro da API.