Como funciona
- O cliente gera um identificador único (UUID) para cada operação.
- Envia o valor no cabeçalho
IdempotencyKey. - A Delfinance armazena a resposta associada a essa chave por 24 horas.
- 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/paymentsPOST /v1/transfersPOST /v1/refundsPOST /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.

