Novas tentativas e idempotência

Esta página explica como o Midaz protege contra duplicação com chaves de idempotência, e como usá-las ao repetir uma requisição.

Tornando as novas tentativas seguras

Requisições de API que falham são comuns. Ocorre um timeout de rede, ou seu serviço cai logo depois de enviar uma requisição. Repetir é natural, e você precisa ter certeza de que o Midaz não vai processar a mesma operação duas vezes. Ao anexar uma chave única a cada requisição, você está dizendo ao Midaz: “Esta é a mesma operação. Se você já processou, não faça de novo.” O Midaz armazena essa chave temporariamente e a usa para determinar se a requisição é nova, está completa ou ainda está em andamento. Isso protege seu sistema contra duplicatas.

Idempotência no Midaz

O header X-Idempotency está disponível em todos os endpoints de criação de transação: no /v1, json, inflow, outflow, annotation, block e unblock; no /v2, direct, hold, block, unblock e batch. A reversão não recebe chave própria: o Midaz deriva uma.

As outras APIs da Lerian usam os próprios headers de idempotência, ou nenhum. Esta página foca na idempotência da API do Ledger do Midaz.

Os endpoints de transação commit e cancel usam um lock baseado em Redis para evitar o processamento concorrente da mesma transação, mas não dão suporte a idempotência completa (sem respostas em cache nem header X-Idempotency-Replayed).

Para usá-la, sua requisição pode incluir dois headers:

X-Idempotency: a chave única que identifica a requisição.
X-TTL: o time-to-live (em segundos) pelo qual o Midaz deve armazenar essa chave em cache.

Se você não enviar o header X-Idempotency, o Midaz gera um automaticamente calculando um hash SHA-256 do corpo da requisição. O Midaz, portanto, deduplica corpos de requisição idênticos enviados para a mesma organização e ledger.

Veja o que acontece:

Quando uma nova chave chega, o Midaz a marca como pending, processa a requisição e armazena a resposta completa em cache.
Se você enviar a mesma chave novamente dentro da janela de TTL:
1. Enquanto a operação roda, o Midaz retorna um 409 Conflict (código de erro 0084).
2. Se já terminou e a requisição coincide, o Midaz retorna exatamente a mesma resposta com um status 201 Created e X-Idempotency-Replayed: true.
Se a transação falhar por erros de validação ou saldo insuficiente, o Midaz exclui a chave de idempotência. Você pode então corrigir o problema e repetir com a mesma chave.

O Midaz delimita o escopo das chaves de idempotência por organização e ledger. Você pode, portanto, usar o mesmo valor de chave de forma independente em organizações ou ledgers diferentes, sem conflito.

Resumo do workflow

A Figura 1 mostra o ciclo de vida completo de uma requisição idempotente:

Ciclo de vida completo de uma requisição idempotente no Midaz, desde o recebimento da chave de idempotência até o retorno da resposta em cache ou recém-processada — Figura 1. Ciclo de vida de uma requisição idempotente no Midaz.

Como funciona:

Se a requisição não incluir uma chave de idempotência existente, o Midaz cria uma nova, ou gera uma automaticamente a partir do hash do corpo da requisição. O Midaz então processa a requisição, armazena a resposta e a retorna com X-Idempotency-Replayed: false.
Se a chave já existir:
- Enquanto a operação roda, o Midaz retorna um 409 Conflict.
- Se a operação estiver completa e a requisição coincidir, o Midaz pula a execução e retorna a resposta em cache com um status 201 Created e X-Idempotency-Replayed: true.
Se a requisição original falhou por erros de validação ou de saldo, o Midaz exclui a chave automaticamente. Você pode repetir com segurança usando a mesma chave.

Exemplo de requisição

Veja como enviar uma requisição idempotente para criar uma transação:

POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json HTTP/1.1
X-Idempotency: 7fb8e1d098cd4730bb932d038b3b8651
X-TTL: 60
Content-Type: application/json

{
  "description": "Monthly subscription payment",
  "code": "SUB-2025-001",
  "send": {
    "asset": "USD",
    "value": "1500",
    "source": {
      "from": [
        {
          "accountAlias": "customer-usd-1",
          "amount": {
            "asset": "USD",
            "value": "1500"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "merchant-usd-1",
          "amount": {
            "asset": "USD",
            "value": "1500"
          }
        }
      ]
    }
  }
}

Se a requisição for bem-sucedida e você a enviar novamente dentro de 60 segundos, o Midaz retornará o resultado em cache com:

HTTP/1.1 201 Created
X-Idempotency-Replayed: true

Se você a enviar novamente enquanto o Midaz ainda processa a original, você receberá:

HTTP/1.1 409 Conflict

Geração de chave

Você pode fornecer sua própria chave X-Idempotency ou deixar o Midaz gerar uma automaticamente.

Geração automática de chave

Se você omitir o header X-Idempotency, o Midaz calcula um hash SHA-256 do corpo da requisição e o usa como chave de idempotência. O Midaz, portanto, deduplica o mesmo corpo JSON exato enviado para a mesma organização e ledger. Isso é suficiente para a maioria dos cenários de repetição em que o corpo da requisição não muda entre as tentativas.

Geração de chave personalizada

Use uma chave personalizada quando você precisar:

Correlacionar a chave de idempotência com um ID no seu próprio sistema (por exemplo, um ID de pedido).
Repetir com um corpo de requisição modificado e ainda assim deduplicar (por exemplo, depois de corrigir um campo).
Controlar o formato da chave para fins de log ou auditoria.

A chave deve ser determinística: se você repetir a mesma operação lógica, a chave permanece a mesma. Uma abordagem comum é usar um UUID ou um hash baseado na sua referência interna:

import uuid

# Option 1: Use an existing business ID as the key
idempotency_key = f"order-{order_id}"

# Option 2: Generate a UUID and store it for retries
idempotency_key = str(uuid.uuid4())

Boas práticas

Sempre valide o header `X-Idempotency-Replayed`

Quando seu sistema recebe uma resposta de um endpoint de transação, sempre verifique o header de resposta X-Idempotency-Replayed antes de processar o resultado. Esse header diz se a resposta vem de uma nova operação ou de uma repetição em cache:

X-Idempotency-Replayed: false: esta é uma resposta nova. O Midaz acabou de processar a transação.
X-Idempotency-Replayed: true: esta resposta vem do cache. O Midaz já processou a transação.

Não verificar esse header é um erro comum de integração. Sem isso, seu sistema pode interpretar uma resposta repetida como uma nova transação. Isso cria processamento duplicado do seu lado, mesmo que o Midaz tenha executado a operação apenas uma vez.

Por exemplo, se seu sistema liquida boletos (guias de cobrança bancária) com base em respostas de transação, você deve verificar X-Idempotency-Replayed para evitar liquidar o mesmo boleto duas vezes.

Use chaves de idempotência explícitas para fluxos críticos

Embora o Midaz gere chaves automaticamente a partir do corpo da requisição, para fluxos financeiros críticos (liquidações, repasses, transferências), sempre forneça uma chave X-Idempotency explícita vinculada ao ID do seu processo de negócio. Isso dá a você:

Depois que a primeira requisição é concluída com sucesso, uma nova tentativa com o corpo alterado dentro da janela de TTL recebe 409 (0084) em vez de uma segunda transação.
Uma trilha de auditoria clara ligando as transações do Midaz às suas operações internas.
Proteção contra casos extremos em que a serialização da requisição pode diferir.

Defina valores de TTL apropriados

Escolha valores de TTL que correspondam à sua janela de repetição:

Para operações síncronas com repetições rápidas: 60–120 segundos.
Para workflows assíncronos com possíveis atrasos: 300–600 segundos.
Para processamento em lote com janelas de repetição longas: considere TTLs mais longos e chaves explícitas.

Estratégia de repetição

Use estes padrões para cenários de falha diferentes:

Falhas que permitem repetição

Estas falhas são seguras para repetir com a mesma chave de idempotência:

Cenário	O que fazer
Timeout de rede ou erro de conexão	Repita com a mesma chave e o mesmo corpo. Se a requisição original foi processada, você receberá a resposta em cache.
Erro de servidor `5xx`	Repita com backoff exponencial. O servidor pode estar temporariamente sobrecarregado.
`409 Conflict` (`0084`), mesmo corpo	Ainda não há resposta armazenada para a chave. Repita depois de um curto intervalo.
Erro de validação ou de saldo	Corrija o problema na sua requisição e então repita com a mesma chave de idempotência (o Midaz exclui a chave nessas falhas).

Falhas que não permitem repetição

Estas falhas exigem uma abordagem diferente:

Cenário	O que fazer
`400 Bad Request` (erro de schema)	Corrija o formato da requisição. Não repita o mesmo payload.
`401 Unauthorized` / `403 Forbidden`	Verifique suas credenciais de autenticação. Repetir não vai ajudar.
`404 Not Found`	Verifique os IDs de organização, ledger ou conta no path da sua requisição.

Backoff exponencial

Para erros transitórios, use backoff exponencial com jitter para evitar sobrecarregar o servidor.

Prevenindo duplicação de entidade

Para alguns endpoints, você não precisa de chaves de idempotência para evitar duplicação. O Midaz aplica restrições de unicidade em recursos críticos. Se você tentar criar uma entidade que conflite com uma existente, o sistema bloqueia a requisição e retorna um 409 Conflict com um erro descritivo:

Recurso	Campo único	Código de erro
Ledger	Nome (dentro da organização)	`0002`
Asset	Nome ou código (dentro do ledger)	`0003`
Segment	Nome (dentro do ledger)	`0015`
Account	Alias (dentro da organização e do ledger)	`0020`
Account Type	Valor da chave (dentro da organização e do ledger)	`0108`

Ao contrário das chaves de idempotência, essas restrições são permanentes e não expiram.

Idempotência entre produtos Lerian

As outras APIs da Lerian definem os próprios headers, escopos e sinais de repetição de idempotência, e algumas não aceitam nenhum header de idempotência. Consulte a referência da API do produto que você chama antes de repetir um comando.

Perguntas frequentes

O que acontece se eu não enviar uma chave de idempotência?

O Midaz gera uma automaticamente calculando um hash SHA-256 do corpo da requisição. O Midaz, portanto, deduplica corpos de requisição idênticos enviados para a mesma organização e ledger. Você apenas precisa fornecer uma chave personalizada se quiser controlar a deduplicação de forma independente do corpo da requisição.

Posso reutilizar uma chave em organizações ou ledgers diferentes?

Sim. O Midaz delimita o escopo das chaves de idempotência por organização e ledger. O mesmo valor de chave usado em organizações ou ledgers diferentes não gera conflito. No entanto, dentro da mesma organização e ledger, cada chave deve ser única por operação.

Posso reutilizar uma chave em endpoints diferentes?

Não. Use uma chave única para cada operação distinta.

O que acontece se eu mudar o TTL em uma repetição?

O Midaz usa apenas o TTL da primeira requisição. Mudá-lo depois não tem efeito.

A resposta repetida sempre será idêntica?

Sim. O Midaz repete a resposta completa, incluindo o status (201 Created) e o corpo, para requisições concluídas.

Qual é o TTL padrão se eu não enviar X-TTL?

A janela padrão é de 300 segundos (5 minutos).

O que acontece se a requisição original falhar?

Se a transação falhar por erros de validação ou saldo insuficiente, o Midaz exclui a chave de idempotência do cache. Você pode então corrigir o problema e repetir com a mesma chave.

Visão geral

Fundamentos de integração

Estabilidade e qualidade

Dicionário de campos

Streaming de eventos

Novas tentativas e idempotência

Tornando as novas tentativas seguras

Idempotência no Midaz

Resumo do workflow

Exemplo de requisição

Geração de chave

Geração automática de chave

Geração de chave personalizada

Boas práticas

Sempre valide o header `X-Idempotency-Replayed`

Use chaves de idempotência explícitas para fluxos críticos

Defina valores de TTL apropriados

Estratégia de repetição

Falhas que permitem repetição

Falhas que não permitem repetição

Backoff exponencial

Prevenindo duplicação de entidade

Idempotência entre produtos Lerian

Perguntas frequentes

​Tornando as novas tentativas seguras

​Idempotência no Midaz

​Resumo do workflow

​Exemplo de requisição

​Geração de chave

​Geração automática de chave

​Geração de chave personalizada

​Boas práticas

​Sempre valide o header X-Idempotency-Replayed

​Use chaves de idempotência explícitas para fluxos críticos

​Defina valores de TTL apropriados

​Estratégia de repetição

​Falhas que permitem repetição

​Falhas que não permitem repetição

​Backoff exponencial

​Prevenindo duplicação de entidade

​Idempotência entre produtos Lerian

​Perguntas frequentes

Tornando as novas tentativas seguras

Idempotência no Midaz

Resumo do workflow

Exemplo de requisição

Geração de chave

Geração automática de chave

Geração de chave personalizada

Boas práticas

Sempre valide o header `X-Idempotency-Replayed`

Use chaves de idempotência explícitas para fluxos críticos

Defina valores de TTL apropriados

Estratégia de repetição

Falhas que permitem repetição

Falhas que não permitem repetição

Backoff exponencial

Prevenindo duplicação de entidade

Idempotência entre produtos Lerian

Perguntas frequentes