La mayoría de las aplicaciones web modernas se comunican con un servidor todo el tiempo. La JavaScript Fetch API es la forma estándar de hacerlo y está integrada en los navegadores y en Node.js 18 y posteriores, por lo que no hay nada que instalar.

El uso básico requiere dos líneas, sin embargo, muchos tutoriales se detienen ahí y omiten la parte que causa errores reales: el manejo de fallas. Probamos los ejemplos de esta guía en un pequeño servidor local en Node.js 24 y el resultado que se muestra proviene de esa ejecución. example.com en el código representa su propia API. Si las promesas son nuevas para usted, comience con la Explicación de las promesas de JavaScript.

¿Qué es la API de recuperación?

Fetch es una interfaz basada en promesas para realizar solicitudes HTTP. Reemplazó al antiguo XMLHttpRequest basado en devolución de llamadas, y muchos proyectos ahora lo usan en lugar de agregar una biblioteca para llamadas simples.

Una solicitud GET

Fetch realiza una solicitud GET de forma predeterminada. Hay dos pasos y cada uno necesita await: primero llegan los encabezados de respuesta y luego lees el cuerpo.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

Los dos pasos existen porque el cuerpo puede ser grande y llegar más tarde que las cabeceras. En un script de navegador, el nivel superior await necesita un módulo, por lo que normalmente lo colocarás dentro de una función async. Consulte nuestra guía de JavaScript async/await.

El objeto de respuesta

Antes de leer el cuerpo, puedes inspeccionar la respuesta:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Un cuerpo sólo se puede leer una vez. Llamar a json() por segunda vez falló en nuestra prueba:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Si necesita leerlo dos veces, llame primero al response.clone().

La gran sorpresa: un 404 no tira

Esto es lo más importante de este artículo. Solicitamos un usuario que no existe:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

No se lanzó ninguna excepción. En lo que respecta a la recuperación, la solicitud funcionó: se contactó al servidor y respondió. La promesa se rechaza sólo cuando no llega ninguna respuesta utilizable, como ocurre con una falla de la red. Entonces un código como este tiene un error oculto:

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Consulte nuestra hoja de referencia de códigos de estado HTTP para ver qué significa cada código.

Un ayudante reutilizable

No repitas ese control en todas partes. Envuélvalo una vez:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Ahora los errores HTTP y los errores de red terminan en lo mismo catch. Vale la pena tener esta pequeña función en cada proyecto. Una versión real también podría leer un mensaje de error del cuerpo de la respuesta y manejar una respuesta 204 No Content, que no tiene JSON para analizar.

PUBLICAR datos JSON

Pase un objeto de opciones como segundo argumento. Para JSON, debes hacer dos cosas tú mismo: convertir los datos en una cadena y configurar el encabezado.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Nuestro servidor de prueba respondió el tipo de contenido que recibió, confirmando que llegó el encabezado. Olvidar ese encabezado es una causa común de errores confusos del servidor, porque muchos marcos solo analizan JSON cuando se declara. Para cargar un formulario o archivos, pase un objeto FormData como cuerpo y no establezca Content-Type, ya que el navegador necesita agregar un valor de límite.

Otros métodos y opciones

¿Elegir entre REST y otros estilos de API? Nuestra comparación de REST vs GraphQL muestra cómo la recuperación encaja con cada uno.

cadenas de consulta

No cree cadenas de consulta uniendo texto, porque los caracteres especiales las romperán. URLSearchParams maneja la codificación por usted:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

El servidor recibió red shoes correctamente, con el espacio restaurado.

Tiempos de espera y cancelaciones

Fetch esperará mucho tiempo en un servidor lento a menos que le indique lo contrario. AbortSignal.timeout() establece un límite. Nuestro punto final de prueba tardó dos segundos, frente a un límite de 200 milisegundos:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Para cancelar manualmente, por ejemplo, cuando un usuario abandona una página o escribe un nuevo término de búsqueda, utilice un AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Para ejecutar varias solicitudes a la vez, use Promise.all, que es mucho más rápido que esperarlas una a la vez:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Todo tipo de fracaso

Así es como se vio cada falla en nuestra ejecución, junto con cómo diferenciarlas:

Esa última fila es común en producción. Un proxy que devuelve un 502 a menudo envía una página de error HTML. Reproducimos esto y res.json() arrojó un SyntaxError. Marcar response.ok antes de analizar significa informar el problema real en lugar de un error de análisis confuso.

CORS y credenciales

En un navegador, una solicitud de un origen a otro está sujeta a CORS, las reglas de intercambio de recursos entre orígenes. Si ve un error que menciona Access-Control-Allow-Origin, la solución pertenece al servidor, que debe permitir su sitio. En su JavaScript, el error aparece solo como un TypeError genérico, así que mire la consola del navegador para conocer el motivo real. Node.js no aplica CORS, por lo que una solicitud que funcione en un script aún puede fallar en el navegador.

De forma predeterminada, los navegadores no envían cookies en solicitudes de origen cruzado. Configure credentials: "include" si los necesita y asegúrese de que el servidor lo permita. Nunca coloque claves API secretas en el JavaScript del navegador, ya que cualquiera puede leerlas. Mantenlos en tu servidor.

Errores comunes

• No marcar response.ok. Las respuestas de error se tratan como exitosas.
• Olvidar el segundo await. response.json() también devuelve una promesa.
• Olvidar JSON.stringify. Pasar un objeto mientras el cuerpo envía [object Object].
• Configurando Content-Type con FormData. Esto rompe el límite, así que déjalo fuera.
• Sin tiempo de espera. Una solicitud colgada puede dejar el control giratorio de una página funcionando indefinidamente.
• Analizando JSON en busca de una respuesta vacía. Un 204 no tiene cuerpo y json() arrojará.

Conclusión

Fetch es simple una vez que recuerdas su regla principal: una respuesta no es lo mismo que un éxito. Copie el pequeño ayudante en su proyecto, agregue un tiempo de espera y pruebe sus rutas de falla. Como siguiente paso, cree una página pequeña que cargue datos desde una API, muestre un mensaje de error claro y permita al usuario cancelar una búsqueda lenta.

Preguntas frecuentes

sigue aprendiendo