Timeouts em Todo Lugar

Defina timeouts para requisições do servidor, chamadas HTTP de saída, consultas ao banco de dados e filas - esperas ilimitadas são a causa mais comum de falhas em cascata em APIs Node.js.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { createServer } from "node:http";
 
const server = createServer(app);
server.requestTimeout = 30_000;
server.headersTimeout = 35_000;
server.keepAliveTimeout = 65_000;
 
const data = await fetch(url, { signal: AbortSignal.timeout(5_000) });

Quando usar isso:

• Picos de latência p99 com CPU estável (threads esperando, não trabalhando).
• Pool de conexões esgotado sob carga moderada.
• Load balancer 502/504 durante lentidão downstream.
• Qualquer chamada fetch ou axios sem timeout explícito.

Exemplo Funcional

import express from "express";
import { createServer } from "node:http";
import pg from "pg";
 
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  connectionTimeoutMillis: 3_000,
  query_timeout: 5_000, // opção node-pg que envolve o timeout da instrução
});
 
const app = express();
 
app.get("/reports/:id", async (req, res) => {
  const controller = AbortController ? new AbortController() : null;
  const deadline = setTimeout(() => controller?.abort(), 8_000);
 
  try {
    const report = await pool.query(
      "SELECT * FROM reports WHERE id = $1",
      [req.params.id]
    );
 
    const enrichment = await fetch(
      `https://analytics.internal/enrich/${req.params.id}`,
      { signal: controller?.signal ?? AbortSignal.timeout(8_000) }
    );
 
    if (!enrichment.ok) {
      return res.status(502).json({ error: "Analytics unavailable" });
    }
 
    res.json({ report: report.rows[0], analytics: await enrichment.json() });
  } catch (err) {
    if ((err as Error).name === "AbortError") {
      return res.status(504).json({ error: "Upstream timeout" });
    }
    throw err;
  } finally {
    clearTimeout(deadline);
  }
});
 
const server = createServer(app);
server.requestTimeout = 30_000;
server.listen(3000);

O que isso demonstra:

• Timeout de conexão do pool de banco de dados vs. timeout de consulta - diferentes modos de falha.
• fetch de saída limitado a 8s - menor que o timeout de requisição do servidor de 30s.
• AbortError mapeado para 504 Gateway Timeout para clientes.
• Timeouts de createServer protegem contra ataques slowloris e sockets travados.

Mergulho Profundo

Como Funciona

• requestTimeout do Servidor - tempo máximo para requisição completa no socket (servidor HTTP Node).
• AbortSignal.timeout - aborta fetch após N ms no Node 18+.
• statement_timeout (Postgres) - o banco de dados encerra consultas longas independentemente do estado do aplicativo.
• Timeouts devem ser em cascata: saída < prazo do manipulador < servidor < load balancer.

Tabela de Orçamento de Tempo Limite

Postgres statement_timeout

SET statement_timeout = '5s';
-- ou por role:
ALTER ROLE app_user SET statement_timeout = '5s';

await pool.query("SET statement_timeout = 5000");

• O encerramento no lado do servidor impede que uma consulta ruim mantenha conexões para sempre.

Equivalente Axios

import axios from "axios";
 
const client = axios.create({ timeout: 5_000 });

• timeout cobre conexão + resposta; use signal: AbortSignal.timeout() para controle mais refinado.

Armadilhas

• Sem timeout no fetch - espera até que o LB mate - esgotamento do pool. Correção: sempre use AbortSignal.timeout.
• Mesmo timeout em todas as camadas - corrida entre LB e 502 do aplicativo. Correção: escalonar orçamentos.
• Retentar sem redução de timeout - amplifica a carga. Correção: timeout menor por tentativa.
• Ignorar headersTimeout - deve exceder ligeiramente keepAliveTimeout no servidor HTTP Node.
• Transações longas sem statement_timeout - mantém conexões do pool. Correção: limite no nível do DB.
• Timeout apenas no caminho feliz - limpe os timers no finally. Correção: evite handles vazados.

Alternativas

FAQs

Relacionados

• Fundamentos de Resiliência - padrões introdutórios
• Retries com Backoff - timeouts por tentativa
• Circuit Breakers - falha rápida quando o downstream está doente
• Desempenho no Express - ajuste de timeout do servidor

Versões da Pilha: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.