Skip to main content
Toda mutação na API Korbit aceita o header Idempotency-Key. Com ele, um retry — timeout, queda de rede, duplo clique — nunca cria o recurso duas vezes nem move dinheiro duas vezes.

​
Como funciona

  1. Envie a mutação com um Idempotency-Key único por operação de negócio (recomendamos um UUID v4 gerado por você).
  2. A API grava a chave com o hash do payload antes de executar o comando.
  3. Resultados possíveis:

​
Regras de ouro

  1. Gere a chave antes de enviar e guarde-a até obter resposta definitiva. Se o seu processador crashar no meio de um request, o retry com a mesma chave conclui com segurança.
  2. Nova intenção de negócio = nova chave. Cobrar o cliente de novo é uma nova operação, com nova chave.
  3. Não altere o payload em retries. Precisa corrigir o valor? Use uma nova chave (é uma nova intenção).
  4. Trate IDEMPOTENCY_IN_PROGRESS com espera curta + retry — significa que a primeira chamada está viva, não morta.

​
Onde a chave é obrigatória

Todas as mutações financeiras e de catálogo aceitam Idempotency-Key; nos comandos de movimentação de dinheiro (payment intents, payouts, refunds) ela é exigida. O Idempotency-Key é escopado à sua conta (tenant): chaves de merchants diferentes nunca colidem.