Idempotência
Como repetir uma criação sem cobrar duas vezes.
Rede cai, timeout acontece. Para que um retry nunca crie uma segunda cobrança, todo POST da API exige o
header Idempotency-Key:
Idempotency-Key: 6f1c2a9e-3b7d-4c1e-9a2f-5d8e7b6c4a10Regras
- Gere uma chave nova para cada operação (um UUID v4 serve) e guarde-a junto do pedido no seu sistema, antes de chamar a API.
- Num retry da mesma operação, reenvie a mesma chave com o mesmo corpo. A API não executa de novo: devolve a resposta da primeira chamada, com o mesmo status e corpo.
- A chave vale por 24 horas e é sua: dois lojistas podem usar o mesmo valor sem conflito.
- Tamanho máximo: 64 caracteres.
Respostas
| Situação | Resposta |
|---|---|
| Chave nova | A operação é executada normalmente. |
| Chave já usada, mesmo corpo | A resposta original, inclusive se tiver sido um erro. |
| Chave já usada com outro corpo ou em outro endpoint | 422: é reuso indevido da chave, não um retry. |
| A primeira chamada com a chave ainda está em andamento | 409: aguarde alguns segundos e repita. |
| Header ausente, vazio ou com mais de 64 caracteres | 400 |
Depois de um erro 5xx
A resposta de erro também fica gravada na chave: repetir com a mesma chave devolve o mesmo erro. O que fazer depende do status:
502(falha ao falar com o provedor de pagamento): a cobrança pode ter sido criada. Antes de tentar com uma chave nova, consulte as cobranças do pagador criadas nos últimos minutos (payerDocumentecreatedFrom).503(forma de pagamento indisponível): nada foi criado. Tente mais tarde com uma chave nova.- Timeout sem resposta: repita com a mesma chave. Se a primeira chamada terminou, você recebe o
resultado dela; se ainda estiver em andamento,
409.