Conceitos
Idempotência
Rede cai, timeout acontece e o seu servidor reinicia no meio de uma chamada. A Idempotency-Key garante que repetir a mesma intenção nunca cria uma segunda cobrança.
A regra
Toda requisição que altera algo (POST, PATCH, PUT, DELETE) exige o header Idempotency-Key, com 16 a 128 caracteres visíveis. Gere a chave uma vez por intenção (por exemplo, a partir do id do pedido no seu sistema) e guarde-a junto da intenção. Se precisar refazer a chamada, use a mesma chave.
POST /v1/payments HTTP/1.1
Authorization: Bearer ep_test_...
X-Account-Id: acc_...
Idempotency-Key: pedido-98765-pix-v1
Content-Type: application/json
{"orderId":"ord_01JDY8B1B2C3D4E5F6G7H8J9KB","method":"PIX","dueDate":"2026-11-20"}O que acontece em cada caso
| Situação | Resposta |
|---|---|
| Primeira chamada | Executa e grava a resposta. |
| Mesma chave e mesmo conteúdo | A resposta gravada, com o mesmo status, e o header idempotent-replayed: true. Nada é executado de novo. |
| Mesma chave com outro conteúdo | 409 IDEMPOTENCY_CONFLICT. A intenção original fica intacta. |
| Mesma chave enquanto a primeira ainda está em andamento | 409 REQUEST_IN_PROGRESS. Aguarde um instante e repita com a mesma chave. |
| Sem o header | 400 IDEMPOTENCY_KEY_REQUIRED. |
- O escopo da chave é a organização, o ambiente e o tipo de operação: a mesma chave em rotas diferentes não colide.
- As respostas ficam guardadas por 30 dias.
- O conteúdo comparado é o corpo normalizado (ordem dos campos não importa), sem dados de cartão.
- Na criação de endpoint de webhook e na rotação do segredo, a repetição devolve o recurso sem o segredo: ele só aparece na primeira resposta.
Quando repetir a chamada
Repita com a mesma chave quando a resposta não chegou ou não foi conclusiva:
- timeout, conexão interrompida ou erro de rede depois de enviar;
5xx(o resultado pode ter acontecido);409 REQUEST_IN_PROGRESSe429 TOO_MANY_REQUESTS.
O SDK aplica essas regras sozinho: gera a chave por chamada, repete automaticamente só quando é seguro e, quando o resultado fica incerto, devolve um erro com idempotencyKey para você repetir.