> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/faq/faq-hyperflow/tempo-de-execucao.md).

# 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) |

{% hint style="info" %}
**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.
{% endhint %}

**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:

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

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FDBvADFQAeeDTXDFn9tii%2Fimage.png?alt=media&amp;token=c76730b2-46d8-468e-b637-9e4d5c3bea65" alt=""><figcaption><p><strong>Imagem 01</strong> - Chamada ao API Gateway com o header async: true, retornando o executionId.</p></figcaption></figure>

{% hint style="info" %}
**Dica:** Guarde o **executionId** retornado. Ele é a chave para consultar posteriormente o que aconteceu naquela execução.
{% endhint %}

**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](https://builder.hyperflow.global), 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***.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FQIypgO1bdQEPxexBjbft%2Fimage.png?alt=media&amp;token=f9754352-ea16-4442-bc6c-ab99a0ac24ec" alt=""><figcaption><p><strong>Imagem 02</strong> - Consulta da execução assíncrona no Tempo real, filtrando pelo ID da execução.</p></figcaption></figure>

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.

{% hint style="success" %}
**Pronto!** Com o modo assíncrono você ganha mais tempo de execução e mantém total visibilidade do que aconteceu em cada chamada. ⚡
{% endhint %}

#### 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.

{% hint style="warning" %}
**Importante:** Quando o timeout é atingido, a execução é interrompida no ponto em que estava. Os blocos seguintes não serão executados.
{% endhint %}

#### 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.

{% hint style="success" %}
**Pronto!** Agora você conhece os limites de execução da Hyperflow e sabe como estruturar seus fluxos para que rodem dentro do tempo esperado. ⏱️
{% endhint %}