Controle de Idempotência

22 min

O controle de idempotência no gateway Fluid permite que você envie a mesma requisição múltiplas vezes de forma segura, garantindo que apenas uma execução será processada mesmo em casos de falhas de rede, timeouts ou tentativas acidentais de reenvio.

Quando usar idempotência

A idempotência é essencial em cenários onde é crítico evitar processamento duplicado:

Pagamentos e transações financeiras

Criação de pedidos ou registros únicos

Integrações com sistemas externos que podem falhar

Webhooks que podem ser reenviados

Como funciona

Headers de request

Para usar idempotência, inclua o header X-Idempotency-Key em sua requisição ao gateway:

curl --location '{gateway_host}/{path}/{flow_name}?key={api_key}' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: pagamento-usuario123-20240115' \ --data '{ "valor": 100.00, "usuario_id": "123" }'

Formato da chave de idempotência:

Tamanho: Entre 3 e 128 caracteres

Caracteres permitidos: Letras, números, hífen (-), underscore (_) e ponto (.)

Recomendação: Use um identificador único e descritivo do contexto

Exemplos válidos:

pagamento-123-20240115

pedido_usuario456_v2

webhook.retry.001

Chaves inválidas retornam erro 400:

# Resposta para chave inválida: HTTP/1.1 400 Bad Request { "code": "400", "message": "invalid idempotency key: invalid characters" }

Headers de response

O Gateway retorna informações sobre o status da idempotência:

X-Idempotency-Key: pagamento-usuario123-20240115 X-Idempotency-Status: new

Status possíveis:

new: Primeira execução desta chave

processing: Execução em andamento

duplicate: Requisição duplicada (já processada)

O controle de idempotência não verifica os detalhes da requisição (como o corpo) para identificar se já foi ou não processada. Esse controle é realizado exclusivamente pelo cabeçalho X-Idempotency-Key e X-Force-Retry.

TTL Policies

A política de tempo de vida do controle de idempotência segue a tabela abaixo:

Status do fluxo	TTL	Motivo
Sucesso \| Info	24h	Sucesso - evitar reprocessamento
Erro \| Falha	5 min	Erro temporário - retry rápido
Divergência	2h	Erro cliente - evitar spam

Comportamento por tipo de execução de fluxo

Fluxos Assíncronos (padrão)

Primeira requisição:

curl --location '{gateway_host}/v2/flows/processar-pagamento?key={api_key}' \ --header 'X-Idempotency-Key: pag-123' \ --data '{"valor": 100}' # Resposta: 200 OK # Headers: # X-Idempotency-Key: pag-123 # X-Idempotency-Status: new { "event_id": "evt_abc123" }

Requisição duplicada:

# Mesma requisição enviada novamente curl --location '{gateway_host}/v2/flows/processar-pagamento?key={api_key}' \ --header 'X-Idempotency-Key: pag-123' \ --data '{"valor": 100}' # Resposta: 200 OK (mesmo event_id) # Headers: # X-Idempotency-Key: pag-123 # X-Idempotency-Status: duplicate { "event_id": "evt_abc123" }

Fluxos Síncronos

Para fluxos síncronos, requisições duplicadas não retornam o resultado original:

curl --location '{gateway_host}/v2/flows/validar-dados?sync=true&key={api_key}' \ --header 'X-Idempotency-Key: validacao-456' \ --data '{"documento": "123456789"}'

Primeira execução:

HTTP/1.1 200 OK X-Idempotency-Key: validacao-456 X-Idempotency-Status: new {"resultado": "documento_valido"}

Execução duplicada:

HTTP/1.1 200 OK X-Idempotency-Key: validacao-456 X-Idempotency-Status: duplicate (vazio)

Execução ainda processando:

HTTP/1.1 200 OK X-Idempotency-Key: validacao-456 X-Idempotency-Status: processing (vazio)

Limitação atual: Para fluxos síncronos, requisições duplicadas retornam body vazio. O resultado original não é cacheado, apenas os metadados da execução.

Forçando nova execução: Force Retry

Em casos onde você deseja reprocessar algum evento que já foi executado com uma chave de idempotência, use o header X-Force-Retry:

curl --location '{gateway_host}/v2/flows/processar-pagamento?key={api_key}' \ --header 'X-Idempotency-Key: pag-123' \ --header 'X-Force-Retry: true' \ --data '{"valor": 100}'

Códigos de status e erros

Status HTTP

Todas as requisições com idempotência retornam 200 OK quando bem-sucedidas, independentemente de ser uma execução nova ou duplicada. A diferenciação é feita através dos headers.

Erros comuns

Chave de idempotência inválida (400 Bad Request):

curl --location '{gateway_host}/v2/flows/test?key={api_key}' \ --header 'X-Idempotency-Key: chave inválida!' \ --data '{}' # Resposta: HTTP/1.1 400 Bad Request { "code": "400", "message": "invalid idempotency key: idempotency key contains invalid characters (allowed: a-z, A-Z, 0-9, ., _, -)" }

Chave muito pequena ou muito grande:

# Chave muito pequena (< 3 caracteres) X-Idempotency-Key: ab # Chave muito grande (> 128 caracteres) X-Idempotency-Key: [string com 129+ caracteres] # Resposta: HTTP/1.1 400 Bad Request { "code": "400", "message": "invalid idempotency key: idempotency key too short (min 3 chars)" }

Outros erros não relacionados à idempotência:

# Flow não encontrado HTTP/1.1 400 Bad Request { "code": "400", "message": "missing 'flow' parameter in path" } # API Key inválida HTTP/1.1 401 Unauthorized { "code": "401", "message": "unauthorized" }

Combinando com outros parâmetros

A idempotência funciona normalmente com todos os outros recursos do Gateway:

# Fluxo síncrono com idempotência e tags
curl --location '{gateway_host}/v2/flows/processar-pedido?sync=true&return_step=resposta&tags=ecommerce,urgente&key={api_key}' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: pedido-789-retry-001' \
--data '{
    "produtos": [{"id": 1, "quantidade": 2}],
    "cliente_id": "user_456"
}'

Boas práticas

Gerando chaves de idempotência

✅ Boas práticas:

// Incluir contexto + timestamp + identificador único const key = `pagamento-${userId}-${timestamp}-${uuid}`; // Para retry de webhook específico const key = `webhook-${originalEventId}-retry-${attemptNumber}`; // Baseado em dados únicos da transação const key = `pedido-${orderId}-${customerEmail}-${totalAmount}`;

❌ Evite:

// Muito genérico const key = "pagamento-123"; // Baseado apenas em timestamp (pode duplicar) const key = Date.now().toString(); // Caracteres inválidos const key = "pagamento user@123!";

Tratamento de erros

Integração com webhooks

Ao receber webhooks que podem ser reenviados, use uma chave baseada no ID único do evento:

# Webhook do sistema externo curl --location '.../flows/processar-webhook?key={api_key}' \ --header 'X-Idempotency-Key: webhook-${sistemaExterno}-${eventoId}' \ --data '${payloadWebhook}'

Limitações atuais

Resultados síncronos: Por ora, o sistema não cacheia o resultado de execuções síncronas. Requisições duplicadas retornam apenas metadados (event_id, status) sem o corpo da resposta original.

Escopo por tenant: Chaves de idempotência são isoladas por tenant (API Key). A mesma chave pode ser usada por diferentes tenants sem conflito.

Monitoramento

Use os headers de resposta para monitorar o comportamento da idempotência: