StackPractices
intermediate Por Mathias Paulenko

Lógica de Reintento en JavaScript Fetch con Backoff

Reintenta llamadas fetch() fallidas en JavaScript con backoff exponencial, jitter, timeouts con AbortSignal, circuit breaker y POSTs idempotentes.

Visión General

fetch() rechaza la promesa en errores de red pero resuelve en errores HTTP, así que la lógica de reintento tiene que cubrir ambos caminos, y fetch() plano ni siquiera tiene timeout. Esta receta es la versión específica de fetch: backoff exponencial con jitter completo, AbortSignal.timeout() y AbortSignal.any() para deadlines que se combinan con la señal del llamador, manejo de Retry-After en los 429, un circuit breaker que solo cuenta fallos de disponibilidad, e Idempotency-Key para el caso POST. Para la versión agnóstica de lenguaje con ejemplos en Python, Java y Node, mira lógica de reintento con backoff exponencial.

Cuándo usarlo

  • Llamadas a APIs externas que a veces devuelven 5xx, 429 o se quedan colgadas
  • Peticiones HTTP resilientes en el navegador o en Node.js 18+ sin una dependencia pesada
  • Código fan-in donde una dependencia inestable no debería tumbar toda la petición
  • Cualquier reintento que deba componerse con una cancelación que el llamador ya controla

Eso sí, no reintentes a ciegas. Elegir qué reintentar es la decisión que más importa:

Fallo¿Reintentar?Por qué
5xx (500, 502, 503, 504)SíFallo transitorio del lado del servidor
429 + Retry-AfterSíRate limit — espera exactamente lo que pide el servidor
Error de red / timeoutSíNunca llegó al servidor (normalmente)
4xx (400, 401, 403, 404, 422)NoError del cliente — misma petición, mismo resultado
408 Request TimeoutQuizáEl servidor la cerró antes; un reintento es razonable
POST sin idempotenciaNoPuede haber tenido éxito en el servidor antes del fallo

Prerequisitos

  • Node.js 18+ o un navegador moderno (ambos incluyen fetch, AbortSignal.timeout, AbortSignal.any)
  • Un servidor que devuelva códigos de estado correctos y, idealmente, Retry-After en los 429

Solución

1. Reintento básico con backoff exponencial

async function fetchWithRetry(url, options = {}, retries = 3, baseDelay = 1000) {
    for (let attempt = 0; attempt <= retries; attempt++) {
        try {
            const response = await fetch(url, options);

            if (response.ok) return response;

            if (response.status >= 500 && attempt < retries) {
                await sleep(baseDelay * 2 ** attempt);
                continue;
            }

            return response;
        } catch (err) {
            if (attempt < retries) {
                await sleep(baseDelay * 2 ** attempt);
                continue;
            }
            throw err;
        }
    }
}

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

const res = await fetchWithRetry("https://api.example.com/data");
const data = await res.json();

2. Timeout, jitter completo y Retry-After

async function fetchWithRetry(url, options = {}, config = {}) {
    const {
        retries = 3,
        baseDelay = 1000,
        maxDelay = 30000,
        timeoutMs = 10000
    } = config;

    for (let attempt = 0; attempt <= retries; attempt++) {
        // AbortSignal.timeout para el deadline, combinado con la señal del
        // llamador para que una cancelación externa también aborte el intento
        const signal = options.signal
            ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)])
            : AbortSignal.timeout(timeoutMs);

        try {
            const response = await fetch(url, { ...options, signal });

            if (response.ok) return response;

            if (response.status === 429 && attempt < retries) {
                const retryAfter = parseInt(response.headers.get("Retry-After") || "0", 10);
                const wait = retryAfter > 0
                    ? retryAfter * 1000
                    : jitterDelay(attempt, baseDelay, maxDelay);
                await sleep(wait);
                continue;
            }

            if (response.status >= 500 && attempt < retries) {
                await sleep(jitterDelay(attempt, baseDelay, maxDelay));
                continue;
            }

            return response; // 4xx y similares — sin reintento
        } catch (err) {
            // Un AbortError por nuestro timeout SÍ es reintentable; si viene
            // de la señal del llamador significa "cancelar", así que relanza
            if (options.signal?.aborted) throw err;
            if (attempt < retries) {
                await sleep(jitterDelay(attempt, baseDelay, maxDelay));
                continue;
            }
            throw err;
        }
    }
}

// Jitter completo — recomendación de AWS: elegir al azar dentro de la
// ventana, no solo añadir ruido sobre el exponencial
function jitterDelay(attempt, baseDelay, maxDelay) {
    const ceiling = Math.min(baseDelay * 2 ** attempt, maxDelay);
    return Math.floor(Math.random() * ceiling);
}

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

3. Wrapper de reintento con circuit breaker

class CircuitBreaker {
    constructor(threshold = 5, resetTimeout = 60000) {
        this.threshold = threshold;
        this.resetTimeout = resetTimeout;
        this.failures = 0;
        this.lastFailureTime = null;
        this.state = "closed";
    }

    recordFailure() {
        this.failures++;
        this.lastFailureTime = Date.now();
        if (this.failures >= this.threshold) this.state = "open";
    }

    recordSuccess() {
        this.failures = 0;
        this.state = "closed";
    }

    canExecute() {
        if (this.state === "open") {
            if (Date.now() - this.lastFailureTime > this.resetTimeout) {
                this.state = "half-open";
                return true;
            }
            return false;
        }
        return true;
    }
}

class FetchWithRetry {
    constructor(config = {}) {
        this.retries = config.retries ?? 3;
        this.baseDelay = config.baseDelay ?? 1000;
        this.maxDelay = config.maxDelay ?? 30000;
        this.timeoutMs = config.timeoutMs ?? 10000;
        this.breaker = new CircuitBreaker(
            config.breakerThreshold ?? 5,
            config.breakerResetTimeout ?? 60000
        );
    }

    // Solo los fallos de disponibilidad deberían disparar el breaker.
    // Un 4xx definitivo es problema del cliente, no del servicio.
    isAvailabilityFailure(status) {
        return status >= 500 || status === 429;
    }

    async request(url, options = {}) {
        if (!this.breaker.canExecute()) {
            throw new Error("Circuit breaker is open — requests temporarily blocked");
        }

        for (let attempt = 0; attempt <= this.retries; attempt++) {
            const signal = options.signal
                ? AbortSignal.any([options.signal, AbortSignal.timeout(this.timeoutMs)])
                : AbortSignal.timeout(this.timeoutMs);

            try {
                const response = await fetch(url, { ...options, signal });

                if (response.ok) {
                    this.breaker.recordSuccess();
                    return response;
                }

                if (this.isAvailabilityFailure(response.status)) {
                    this.breaker.recordFailure();
                    if (attempt < this.retries) {
                        await this.waitFor(response, attempt);
                        continue;
                    }
                }

                return response; // estado definitivo — no es evento del breaker
            } catch (err) {
                if (options.signal?.aborted) throw err;
                this.breaker.recordFailure();
                if (attempt < this.retries) {
                    await this.sleep(this.jitter(attempt));
                    continue;
                }
                throw err;
            }
        }
    }

    waitFor(response, attempt) {
        if (response.status === 429) {
            const retryAfter = parseInt(response.headers.get("Retry-After") || "0", 10);
            if (retryAfter > 0) return this.sleep(retryAfter * 1000);
        }
        return this.sleep(this.jitter(attempt));
    }

    jitter(attempt) {
        const ceiling = Math.min(this.baseDelay * 2 ** attempt, this.maxDelay);
        return Math.floor(Math.random() * ceiling);
    }

    sleep(ms) {
        return new Promise(resolve => setTimeout(resolve, ms));
    }
}

const client = new FetchWithRetry({
    retries: 4,
    baseDelay: 500,
    timeoutMs: 8000,
    breakerThreshold: 5,
    breakerResetTimeout: 30000
});

const res = await client.request("https://api.example.com/users");
const data = await res.json();

4. Reintentar un POST de forma segura con Idempotency-Key

Reintentar un POST es peligroso porque el primer intento puede haber tenido éxito en el servidor antes de que cayera la conexión; reintenta a ciegas y terminas con dos pedidos. El arreglo estándar es una clave de idempotencia: un ID único generado por el cliente que el servidor deduplica.

async function postWithRetry(url, body, config = {}) {
    const { retries = 3, baseDelay = 500 } = config;
    // Una clave para TODA la operación lógica — los reintentos la comparten,
    // una operación genuinamente nueva recibe una clave nueva
    const idempotencyKey = crypto.randomUUID();

    for (let attempt = 0; attempt <= retries; attempt++) {
        try {
            const response = await fetch(url, {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    "Idempotency-Key": idempotencyKey
                },
                body: JSON.stringify(body),
                signal: AbortSignal.timeout(10000)
            });

            if (response.ok) return response;
            if (response.status >= 500 && attempt < retries) {
                await sleep(baseDelay * 2 ** attempt);
                continue;
            }
            return response;
        } catch (err) {
            if (attempt < retries) {
                await sleep(baseDelay * 2 ** attempt);
                continue;
            }
            throw err;
        }
    }
}

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

El detalle: el servidor tiene que respetar Idempotency-Key (Stripe lo hace; revisa la doc de tu API). Si no lo hace, reintentar un POST es una moneda al aire: prefiere un endpoint dedicado de “verifica y luego crea”, o haz la operación naturalmente idempotente (PUT con un ID elegido por el cliente).

5. Probar la ruta de reintento con MSW

El código de reintento solo corre de verdad cuando todo ya está en llamas, así que pruébalo explícitamente. MSW intercepta fetch tanto en tests del navegador como en Node:

import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { test, expect, beforeAll, afterAll } from "vitest";

const server = setupServer();
beforeAll(() => server.listen());
afterAll(() => server.close());

test("reintenta dos veces con 503 y luego funciona", async () => {
    let calls = 0;
    server.use(
        http.get("https://api.example.com/data", () => {
            calls++;
            return calls < 3
                ? new HttpResponse(null, { status: 503 })
                : HttpResponse.json({ ok: true });
        })
    );

    const res = await fetchWithRetry("https://api.example.com/data",
        {}, { retries: 3, baseDelay: 1 }); // baseDelay de 1ms mantiene el test rápido
    expect(res.ok).toBe(true);
    expect(calls).toBe(3);
});

Con baseDelay: 1 los tests corren al instante mientras ejercitan toda la ruta de reintento, incluido el conteo de fallos del breaker si lo apuntas a la versión de clase.

Cómo funciona

Mermaid flowchart LR diagram

Dos canales de fallo, dos respuestas. fetch() solo rechaza en errores de red (DNS, TCP, TLS, CORS, abort); cualquier status HTTP, incluido 500 y 404, resuelve normalmente. Así que el wrapper necesita un try/catch para el camino de red y un if (response.ok) para el camino HTTP. Es la misma tabla de decisión de “Cuándo usarlo”, escrita en prosa.

Las matemáticas del backoff, en corto: el intento n espera baseDelay * 2^n milisegundos, con tope en maxDelay. El jitter completo (Math.random() * ceiling) supera a “exponencial más un poco de ruido” porque reparte los reintentos por toda la ventana, y el blog de arquitectura de AWS midió que reduce bastante mejor las estampidas de reintentos sincronizados. Cuando el servidor te dice exactamente cuánto esperar (Retry-After), eso gana sobre cualquier cálculo: el servidor conoce su propio calendario de recuperación.

Los timeouts merecen párrafo aparte porque fetch() no tiene: una petición colgada cuelga para siempre. AbortSignal.timeout(ms) es el one-liner moderno; el patrón antiguo es new AbortController() más un setTimeout(() => controller.abort(), ms) que hay que acordarse de limpiar. AbortSignal.any([a, b]) fusiona señales, lo cual importa cuando el llamador te dio una señal y tú quieres tu propio deadline: combinándolas, cualquiera de las dos aborta el intento. Ojo con el matiz de los ejemplos: un AbortError por timeout es reintentable (saltó nuestro deadline, puede que el servidor solo vaya lento), pero un abort desde la señal del llamador significa “para todo”, así que el código revisa options.signal?.aborted y relanza.

El circuit breaker va por encima de los reintentos, no dentro. Los reintentos manejan un servicio que a veces va lento; el breaker maneja un servicio caído, cortando llamadas por completo para que se recupere. Punto clave del diseño en la versión de clase: solo cuentan para el umbral los fallos de disponibilidad (5xx, 429, red/timeout). Una ráfaga de 404 o 400 legítimos es un bug del llamador, no una caída; contarlos abriría el breaker con tráfico sano.

Finalmente, el tema de entornos: todo esto es fetch estándar, así que corre igual en el navegador y en Node 18+. En Node concretamente, fetch funciona sobre undici, y puedes empujar timeouts y reintentos a la capa del dispatcher en su lugar — new Agent({ connectTimeout, headersTimeout }) más el RetryHandler incorporado de undici — cuando prefieras no envolver cada llamada.

Variantes

EnfoqueComplejidadCaracterísticasCuándo
Reintento básicoBajaBackoff exponencialScripts simples, pocos endpoints
Jitter + timeoutMediaJitter completo, AbortSignal.timeout, Retry-AfterApps de producción en navegador/Node
Clase con circuit breakerAltaConteo de fallos, recuperación fail-fastDependencias críticas
POST con Idempotency-KeyMediaReintentos de mutación segurosPagos, pedidos, registros
RetryHandler de undiciMediaReintentos en la capa del agente HTTPServicios solo-Node, política central

Buenas prácticas

  • Reintenta solo lo que puede fallar transitoriamente: 5xx, 429, errores de red, timeouts. Cualquier otra cosa es un bug que arreglar, no algo que repetir.
  • Limita reintentos y límite de espera. retries: 3 con maxDelay: 30s es un default sano; un bucle de reintentos sin tope amplifica la caída.
  • Respeta Retry-After por encima del backoff calculado siempre que aparezca en un 429.
  • Usa jitter completo, no “exponencial + espolvorear”: Math.random() * ceiling reparte mejor la manada.
  • Dale a cada intento un deadline: AbortSignal.timeout(), y fusiónalo con la señal del llamador vía AbortSignal.any() cuando existan ambas.
  • Solo reintenta POSTs con una historia de idempotencia: soporte de Idempotency-Key, un endpoint de verifica-y-crea, o semántica PUT.
  • Registra cada intento con su número y el status/error — los fallos intermitentes son imposibles de depurar a ciegas.

Errores comunes

  • Reintentar POSTs a pelo. El primer intento puede haberse confirmado en el servidor; el reintento crea un duplicado. Sin clave de idempotencia, no lo reintentes.
  • Sin timeout. fetch() no trae deadline incorporado, y una petición colgada bloquea cada reintento. Es la forma más común en que el código de reintento falla en producción.
  • Reintentar 4xx. Un 401 o un 422 devuelve la misma respuesta siempre; solo añades latencia a un fallo garantizado.
  • Reintentos de espera fija. Cada 1s es carga constante sobre un servidor en apuros y una estampida cuando muchos clientes lo hacen a la vez.
  • Contar errores definitivos en el breaker. Un montón de 404 no es una caída; si el breaker los cuenta, se abre con tráfico sano y bloquea peticiones buenas.
  • Ignorar la señal del llamador. Combinar options.signal con tu timeout vía AbortSignal.any() mantiene viva la cancelación externa; options.signal || controller.signal desactiva tu timeout en silencio.

Lecturas relacionadas

Preguntas frecuentes

¿Debería reintentar errores 4xx?

No. Los 400, 401, 403, 404 y 422 son errores del cliente, así que reintentar la misma petición devuelve el mismo resultado. La única excepción parcial es 408 Request Timeout, que algunos servidores emiten de forma transitoria; un reintento cauto es defendible. Todo lo demás 4xx: corrige la petición, no la repitas.

¿En qué se diferencia esto de los plugins de reintento de axios?

Misma idea, otro cableado. Axios rechaza en no-2xx, así que las comprobaciones van en el catch leyendo error.response.status en lugar de response.ok. Librerías como axios-retry manejan el backoff por ti; con fetch no hay equivalente incorporado, que es justo por qué lo envuelves tú mismo, o usas ky, que trae reintento y timeout de fábrica.

¿AbortSignal.timeout fuga memoria si la petición termina antes?

No — AbortSignal.timeout(ms) agenda un timer que la plataforma limpia cuando la señal pasa por el recolector, y solo dispara si el timeout realmente vence. El patrón manual AbortController + setTimeout es el que sí fuga si olvidas el clearTimeout (y puede abortar de más si el controller sobrevive a la petición).

¿Cómo pruebo la lógica de reintento sin esperar segundos de verdad?

Dos palancas: inyecta la espera (pasa baseDelay: 1 o una función sleep en config) y mockea el servidor. MSW intercepta fetch en tests de Node y del navegador; para un test unitario puro, un fetch falso que devuelva 503, 503, 200 en secuencia también sirve. Verifica el número de llamadas en lugar del tiempo transcurrido.

¿Debería el circuit breaker contar fallos 4xx?

En general no — el breaker existe para proteger un servicio que está fallando, y un 4xx es problema del llamador. Contarlos significa que un cliente con bugs puede abrir el breaker y bloquear peticiones sanas. Cuenta 5xx, 429, timeouts y errores de red; trata los estados definitivos como neutros.