API
Idempotência
Repita uma chamada sem criar nada em dobro.
Rede cai, timeout acontece. Para repetir um POST sem criar dois pedidos, mande o header Idempotency-Key com um valor único por operação (o id do pedido no seu sistema, um UUID):
Idempotency-Key: pedido_123- A primeira chamada com a chave roda normalmente; as seguintes, com o mesmo corpo, devolvem a mesma resposta, sem executar de novo.
- A chave tem de 8 a 255 caracteres (letras, números e
. _ : -) e vale por chave de API e por rota: repetir com outra chave de API executa de novo. - A mesma chave com outro corpo dá
422 idempotency_key_reused. - A resposta fica guardada por 24 horas a partir da primeira chamada. Depois disso a chave pode ser usada de novo e a chamada roda outra vez.
- Enquanto a primeira ainda está rodando, a repetição recebe
409 idempotency_in_progress.
Vale para todo POST. É obrigatória (sem ela: 400 idempotency_key_required) em:
A referência marca o header como obrigatório nessas rotas. Rotas que devolvem um segredo (criar webhook, trocar segredo) ignoram o header.