⏰Tempo de execução

Definição do tempo limite de execução dos fluxos

Tempo máximo de execução dos fluxos (Timeout)

O que é o tempo máximo de execução?

Todo fluxo na Hyperflow possui um tempo máximo de execução, também chamado de timeout. Esse limite define por quanto tempo uma execução pode permanecer ativa antes de ser encerrada automaticamente pela plataforma.

O timeout existe para garantir a estabilidade e a performance da plataforma, evitando que execuções travadas ou muito demoradas consumam recursos indefinidamente e prejudiquem o atendimento dos seus usuários.

1. Tabela de timeouts por tipo de execução

O tempo máximo varia de acordo com a forma como o fluxo foi iniciado:

Tipo de execução	Tempo máximo
Fluxo normal (ao receber mensagem em um canal conversacional (WhatsApp, Instagram, Messenger, outros...)	60 segundos
Fluxo ativado por Webhooks ou Transmissão	60 segundos
API Gateway padrão	30 segundos
API Gateway assíncrono (Veja mais detalhes abaixo)	120 segundos (2 minutos)

Atenção: O tempo máximo se aplica à execução corrente, ou seja, a cada vez que o fluxo é disparado. Quando o fluxo aguarda uma resposta do usuário, a execução é encerrada e uma nova execução se inicia quando a próxima mensagem chega.

1.1 O que é o API Gateway assíncrono?

Por padrão, ao chamar uma rota do API Gateway, a requisição fica aguardando até que o fluxo termine de executar para então receber a resposta. Isso significa que o sistema que fez a chamada precisa esperar o processamento completo, respeitando o limite de 30 segundos.

O modo assíncrono funciona de forma diferente: a chamada retorna imediatamente, e o fluxo continua sendo executado em segundo plano, com um limite maior de 120 segundos. É a opção ideal para processamentos mais pesados, que envolvem várias chamadas de API ou integrações mais lentas, e nos quais o sistema de origem não precisa aguardar o resultado na mesma requisição.

Como utilizar

Para executar uma rota de forma assíncrona, basta chamar a rota do API Gateway normalmente, incluindo no header da requisição a propriedade:

async: true

Ao fazer isso, a chamada não aguarda a execução do fluxo e retorna imediatamente um executionId, que identifica aquela execução:

{
  "executionId": "c46a4401-a251-40c8-935e-e13569673f57"
}

Imagem 01 - Chamada ao API Gateway com o header async: true, retornando o executionId.

Dica: Guarde o executionId retornado. Ele é a chave para consultar posteriormente o que aconteceu naquela execução.

Como consultar uma execução assíncrona

Como a resposta da chamada não traz o resultado do fluxo, a consulta do que aconteceu é feita pelo Tempo real.

• Acesse o Tempo real: No menu esquerdo do builder Hyperflow, clique em Tempo real e selecione a aba API.

• Filtre pelo ID: No campo de consulta, informe o executionId retornado na chamada, no formato id = "SEU_EXECUTION_ID".

• Execute a consulta: Clique em Executar consulta.

Imagem 02 - Consulta da execução assíncrona no Tempo real, filtrando pelo ID da execução.

Dessa forma, você consegue visualizar toda a orquestração que rodou de forma assíncrona: a requisição recebida, o Trace com cada bloco executado e seus tempos, e a Resposta gerada pelo fluxo.

Pronto! Com o modo assíncrono você ganha mais tempo de execução e mantém total visibilidade do que aconteceu em cada chamada. ⚡

2. O timeout considera a execução completa

É importante entender que o limite se refere ao tempo total da execução, e não a cada etapa isoladamente.

Exemplo: Se o seu fluxo realiza três chamadas de API em sequência, a soma do tempo das três chamadas (somado ao processamento dos demais blocos) não pode ultrapassar o timeout definido.

Chamada	Tempo de resposta
API 1	25 segundos
API 2	20 segundos
API 3	20 segundos
Total	65 segundos

No exemplo acima, em um fluxo normal (60 segundos), a execução seria encerrada antes de concluir a terceira chamada, pois o tempo acumulado ultrapassou o limite.

Importante: Quando o timeout é atingido, a execução é interrompida no ponto em que estava. Os blocos seguintes não serão executados.

3. Boas práticas para evitar timeouts

• Otimize as APIs externas: Verifique o tempo de resposta dos serviços que o seu fluxo consome. APIs lentas são a causa mais comum de timeouts.

• Evite chamadas sequenciais desnecessárias: Sempre que possível, reduza a quantidade de chamadas externas dentro de uma mesma execução.

• Utilize o API Gateway assíncrono: Para processamentos mais longos, prefira o modo assíncrono, que oferece até 120 segundos de execução.

• Divida fluxos complexos: Quebre processamentos pesados em etapas menores, utilizando a interação com o usuário para separar execuções.

Pronto! Agora você conhece os limites de execução da Hyperflow e sabe como estruturar seus fluxos para que rodem dentro do tempo esperado. ⏱️