Erro 408 - Read Timed Out

O erro 408 - Read Timed Out nos Logs de Webhooks indica que a conexão com seu servidor foi estabelecida, mas o Asaas não recebeu a resposta dentro do tempo esperado.

Como funciona o timeout

Após enviar o Webhook, o Asaas aguarda até 10 segundos pela resposta do endpoint.

Se não receber HTTP 200 nesse período, a tentativa é considerada uma falha e pode ser reenviada.

Uma resposta enviada depois do timeout não altera o resultado daquela tentativa. Por isso, não execute processamentos demorados antes de confirmar o recebimento do evento.

Read Timed Out ou Connect Timed Out?

Os dois erros indicam problemas diferentes.

Se a conexão nem chegou a ser estabelecida, consulte Erro Connect Timed Out.

Principais causas

O Read Timed Out pode ocorrer quando o endpoint executa tarefas demoradas antes de responder, como:

• consultas lentas ao banco de dados;
• chamadas para APIs externas;
• geração de arquivos ou relatórios;
• envio de e-mails;
• tarefas complexas executadas de forma síncrona;
• deadlocks ou filas internas congestionadas;
• alto consumo de CPU ou memória;
• indisponibilidade parcial da aplicação.

Fluxo que pode gerar timeout

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas envia o Webhook"] --> B["Aplicação recebe o evento"]
    B --> C["Consultar banco de dados"]
    C --> D["Chamar API externa"]
    D --> E["Gerar relatório"]
    E --> F["Enviar e-mail"]
    F --> G["Retornar HTTP 200<br/>após 15 segundos"]
    G --> H["Registrar<br/>Read Timed Out"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F,G validacao
    class H sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Mesmo que a aplicação responda depois, o Asaas já terá encerrado a tentativa e poderá reenviar o mesmo evento.

Fluxo recomendado

Persista o evento antes de confirmar o recebimento e execute a regra de negócio em segundo plano.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas envia o Webhook"] --> B["Aplicação recebe o evento"]
    B --> C["Persistir o evento"]
    C --> D["Retornar HTTP 200"]
    D --> E["Processar em fila assíncrona"]
    E --> F["Executar regras de negócio"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Esse fluxo reduz o tempo de resposta do endpoint e evita que tarefas internas consumam o limite de 10 segundos.

Como corrigir

1. Meça o tempo de resposta

Monitore o tempo entre o recebimento da requisição e o retorno HTTP 200.

O endpoint precisa responder em até 10 segundos. Reduza esse tempo sempre que possível.

2. Persista antes de processar

Ao receber o evento:

1. identifique o evento pelo campo id;
2. persista o id e os dados necessários;
3. confirme a persistência;
4. retorne HTTP 200;
5. execute a regra de negócio em segundo plano.

Como os Webhooks utilizam o modelo at least once, o mesmo evento pode ser reenviado. Utilize o id para impedir processamento duplicado.

Consulte como implementar idempotência em Webhooks.

3. Remova tarefas demoradas da requisição

Não aguarde, antes do HTTP 200, operações como:

• APIs de terceiros;
• envio de e-mails;
• geração de arquivos;
• consultas demoradas;
• relatórios;
• outras tarefas que possam ser processadas posteriormente.

4. Monitore dependências e infraestrutura

Verifique:

• utilização de CPU e memória;
• tempo de resposta do banco de dados;
• tempo das consultas executadas;
• latência de serviços internos;
• filas ou workers congestionados;
• logs da aplicação.

O que acontece enquanto o timeout persiste

Cada timeout é tratado como uma falha de entrega.

Se as falhas continuarem:

• o evento pode ser reenviado;
• a configuração entra no mecanismo de penalização progressiva;
• após 15 falhas consecutivas, a fila é interrompida;
• novos eventos continuam sendo armazenados;
• eventos pendentes permanecem disponíveis por até 14 dias.

Entenda a Penalização de filas.

Como validar a correção

Após os ajustes:

1. teste o endpoint e confirme que a resposta ocorre em menos de 10 segundos;
2. se a fila estiver interrompida, reative a configuração;
3. gere ou aguarde um novo evento;
4. consulte os Logs de Webhooks;
5. confirme que as novas tentativas retornam HTTP 200 sem Read Timed Out.

A ordem das entregas após a recuperação depende do tipo de envio configurado no Webhook. Não dependa da ordem de chegada quando utilizar envio Não Sequencial.

Próximos passos

• Consulte os Logs de Webhooks
• Implemente idempotência em Webhooks
• Revise o recebimento de eventos
• Entenda a Penalização de filas
• Reative uma fila interrompida
• Diferencie de Connect Timed Out