Skip to main content
Operações de escrita (POST/PUT/PATCH) que envolvem movimentação financeira exigem uma chave de idempotência para evitar processamento duplicado em caso de retries de rede.

Como funciona

  1. O cliente gera um identificador único (UUID) para cada operação.
  2. Envia o valor no cabeçalho IdempotencyKey.
  3. A Delfinance armazena a resposta associada a essa chave por 24 horas.
  4. Qualquer requisição subsequente com a mesma chave retorna a resposta original, sem executar a operação novamente.

Formato da chave

  • Tipo: UUID v4 recomendado.
  • Tamanho: máximo 64 caracteres.
  • Escopo: único por operação (não reutilize para requisições diferentes).

Exemplo de uso

Comportamento

Endpoints que exigem idempotência

  • POST /v1/payments
  • POST /v1/transfers
  • POST /v1/refunds
  • POST /v1/pix
Endpoints de consulta (GET) são naturalmente idempotentes e não exigem o cabeçalho.

Estratégia de retries

1

Gere a chave uma única vez

Antes da primeira tentativa, gere e persista a chave.
2

Reutilize em retries

Em falhas de rede ou timeouts, envie a mesma chave.
3

Aplique backoff exponencial

Aguarde 1s, 2s, 4s, 8s entre tentativas.
4

Limite de tentativas

Máximo de 5 retries. Após isso, escale o erro.
Nunca gere uma nova chave de idempotência em retries — isso pode causar duplicação de operações financeiras.

Erros relacionados