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 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 headers de resposta o gateway retorna informações sobre o status da idempotência 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 requisição duplicada fluxos síncronos para fluxos síncronos, requisições duplicadas não retornam o resultado original primeira execução execução duplicada execução ainda processando \ 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 \ 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) chave muito pequena ou muito grande outros erros não relacionados à idempotência 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 ❌ evite tratamento de erros integração com webhooks ao receber webhooks que podem ser reenviados, use uma chave baseada no id único do evento 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