Idempotência no Gateway Fluid

a idempotência 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 http para usar idempotência, inclua o header x idempotency key em sua requisição curl location '{gateway host}/v2/flows/{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 resposta 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) comportamento por tipo de execução 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 {} execução ainda processando http/1 1 200 ok x idempotency key validacao 456 x idempotency status processing {} \ hint{type="info"} 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 force retry em casos onde uma execução falhou e você deseja forçar uma nova tentativa, 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}' \ hint{type="warning"} o x force retry só funciona para execuções que falharam anteriormente execuções bem sucedidas não podem ser forçadas a reprocessar 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 invalid characters" } 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 key length must be between 3 and 128 characters" } 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 const response = await fetch('/v2/flows/meu fluxo', { method 'post', headers { 'content type' 'application/json', 'x idempotency key' gerarchaveunica(), 'x api key' apikey }, body json stringify(dados) }); const idempotencystatus = response headers get('x idempotency status'); if (idempotencystatus === 'duplicate') { console log('requisição já foi processada anteriormente'); } else if (idempotencystatus === 'processing') { console log('requisição ainda está sendo processada'); } 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 '{gateway host}/v2/flows/processar webhook?key={api key}' \\ \ header 'x idempotency key webhook ${sistemaexterno} ${eventoid}' \\ \ data '${payloadwebhook}' limitações atuais \ hint{type="warning"} 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 \ hint{type="info"} 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 function logidempotencymetrics(response) { const key = response headers get('x idempotency key'); const status = response headers get('x idempotency status'); console log(`idempotency key ${key}, status ${status}`); // métricas para observabilidade if (status === 'duplicate') { metrics increment('gateway idempotency duplicate'); } else if (status === 'new') { metrics increment('gateway idempotency new'); } }