Idempotência e novas tentativas
Como repetir uma requisição sem criar duas cobranças ou duas devoluções.
Toda requisição POST exige o cabeçalho Idempotency-Key (de 8 a 128 caracteres; recomendamos UUID v4).
- A mesma chave com o mesmo corpo devolve a resposta original por 24 horas, com
Idempotent-Replayed: true. - A mesma chave com corpo diferente responde
422 idempotency-key-reused. - Enquanto a primeira requisição ainda está em processamento:
409 idempotency-key-in-progress— espere e repita.
Quando repetir
| Situação | O que fazer |
|---|---|
| Falha de rede, tempo esgotado | Repita com a mesma chave |
429 |
Espere o Retry-After e repita com a mesma chave |
500, 503 bank-unavailable |
Repita com a mesma chave após Retry-After |
Outros 4xx |
Não repita: corrija a requisição |
Os SDKs fazem isso por você: geram a chave, usam a mesma em todas as tentativas e respeitam Retry-After.
Passe a sua própria chave (por exemplo, o número do pedido) para que uma nova execução do seu processo também seja
segura:
pix.charges.create(amount="149.90", external_ref="10293", idempotency_key="pedido-10293")
Dica: use também external_ref — ele é único por unidade e a API recusa uma segunda cobrança com o mesmo valor
(409 external-ref-already-used).