Tiempos de espera en todas partes

Establece tiempos de espera en las solicitudes del servidor, HTTP saliente, consultas de bases de datos y colas; las esperas ilimitadas son la causa más común de interrupciones en cascada de la API de Node.js.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

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) });

Cuándo usarlo:

• Picos de latencia p99 con CPU plana (hilos esperando, no trabajando).
• Pool de conexiones agotado bajo carga moderada.
• Balanceador de carga 502/504 durante la lentitud de la capa inferior.
• Cualquier llamada fetch o axios sin tiempo de espera explícito.

Ejemplo de trabajo

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, // opción de node-pg que envuelve el tiempo de espera de la declaración
});
 
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);

Lo que esto demuestra:

• Tiempo de espera de conexión del pool de la base de datos vs. tiempo de espera de consulta: diferentes modos de fallo.
• fetch saliente limitado a 8s, menos que el tiempo de espera de solicitud del servidor de 30s.
• AbortError mapeado a 504 Gateway Timeout para clientes.
• Los tiempos de espera de createServer protegen contra slowloris y sockets colgados.

Análisis profundo

Cómo funciona

• requestTimeout del servidor - tiempo máximo para una solicitud completa en el socket (servidor HTTP de Node).
• AbortSignal.timeout - aborta fetch después de N ms en Node 18+.
• statement_timeout (Postgres) - la base de datos elimina consultas largas independientemente del estado de la aplicación.
• Los tiempos de espera deben ser en cascada: saliente < plazo del manejador < servidor < balanceador de carga.

Tabla de presupuesto de tiempo de espera

statement_timeout de Postgres

SET statement_timeout = '5s';
-- o por rol:
ALTER ROLE app_user SET statement_timeout = '5s';

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

• La eliminación en el lado del servidor evita que una consulta incorrecta mantenga las conexiones indefinidamente.

Equivalente de Axios

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

• timeout cubre la conexión + la respuesta; usa signal: AbortSignal.timeout() para un control más preciso.

Errores comunes

• Sin tiempo de espera en fetch - espera hasta que el balanceador de carga lo elimine - agotamiento del pool. Solución: siempre AbortSignal.timeout.
• Mismo tiempo de espera en todas las capas - carrera entre el balanceador de carga y la aplicación 502. Solución: escalonar los presupuestos.
• Reintentar sin reducción de tiempo de espera - amplifica la carga. Solución: tiempo de espera más corto por intento.
• Ignorar headersTimeout - debe exceder ligeramente keepAliveTimeout en el servidor HTTP de Node.
• Transacciones largas sin statement_timeout - mantiene las conexiones del pool. Solución: límite a nivel de base de datos.
• Tiempo de espera solo en el camino feliz - borra los temporizadores en finally. Solución: evita manejadores filtrados.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de resiliencia - patrones introductorios
• Reintentos con retroceso - tiempos de espera por intento
• Disyuntores - falla rápidamente cuando la capa inferior está enferma
• Rendimiento en Express - ajuste del tiempo de espera del servidor

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.