Errores Comunes en Integración de APIs REST que Cuestan Dinero

Errores Comunes en Integración de APIs REST que Cuestan Dinero

La integración de APIs REST mal hecha es una de las principales fuentes de bugs en aplicaciones web. Un error en la gestión de tokens, un timeout mal configurado o una gestión incorrecta de errores puede tirarte una plataforma entera durante horas. En este post repasamos los 10 errores más habituales y cómo evitarlos.

Este contenido complementa nuestra Guía Completa de Integración de APIs. Si aún no la has leído, es buen momento para hacerlo.

Error 1: No gestionar correctamente los tokens de autenticación

El error más común en integración de APIs es gestionar mal los tokens de acceso. Muchos desarrolladores guardan el token en localStorage sin expiración, lo cual es un riesgo de seguridad. Otros no implementan el refresh token y se encuentran con autenticaciones que caducan sin previo aviso.

Cómo detectarlo: tu aplicación deja de funcionar de repente y el error en consola dice “401 Unauthorized” o “Token expired”.

Cómo evitarlo: implementa un sistema de refresh token con almacenamiento en cookies HttpOnly. Cuando el token expire, tu aplicación debe llamar automáticamente al endpoint de refresh antes de hacer la petición original.

async function fetchConRetry(url, options, maxIntentos = 3) {
  let response = await fetch(url, options);

  if (response.status === 401) {
    const nuevoToken = await refreshAccessToken();
    if (nuevoToken) {
      options.headers["Authorization"] = `Bearer ${nuevoToken}`;
      response = await fetch(url, options);
    }
  }

  return response;
}

Error 2: Ignorar los códigos de estado HTTP

Muchos desarrolladores solo miran si la petición “funciona” (código 200) o “falla” (código 400/500). Pero cada código de estado tiene un significado específico que deberías gestionar.

• 200 OK: todo bien, procesa la respuesta
• 201 Created: el recurso se creó correctamente
• 400 Bad Request: tu petición tiene un formato incorrecto
• 401 Unauthorized: no estás autenticado
• 403 Forbidden: estás autenticado pero no tienes permisos
• 404 Not Found: el recurso no existe
• 429 Too Many Requests: estás superando el rate limit
• 500 Internal Server Error: error del servidor, no es tu culpa

Cómo evitarlo: crea una capa de abstracción que gestione cada código de estado de forma adecuada. No trates igual un 429 (rate limit, esperar y reintentar) que un 404 (el recurso se ha eliminado).

Error 3: No implementar reintentos con backoff exponencial

Las APIs fallan. La red falla. Un timeout de red no significa que la operación haya fallado. Si no implementas reintentos automáticos con backoff exponencial, perderás peticiones legítimas.

Backoff exponencial significa: reintentas al segundo 1, luego 2, luego 4, luego 8. Esto evita saturar una API que está teniendo problemas.

async function fetchConBackoff(url, opciones, maxReintentos = 4) {
  for (let i = 0; i < maxReintentos; i++) {
    try {
      const response = await fetch(url, opciones);
      if (!response.ok && response.status >= 500) {
        throw new Error(`HTTP ${response.status}`);
      }
      return response;
    } catch (error) {
      if (i === maxReintentos - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

Error 4: No validar los datos de respuesta

Asumir que la respuesta de una API siempre tiene el formato esperado es peligroso. Las APIs cambian, las versiones se actualizan y los campos pueden desaparecer o renombrarse.

Cómo evitarlo: valida siempre la respuesta con un esquema (Zod, Joi, TypeScript types). Si falta un campo, tu aplicación debe gestionarlo correctamente, no romperse.

Error 5: Enviar información sensible en la URL

Los parámetros de query aparecen en logs de servidores, historial del navegador y pueden compartirse accidentalmente. Nunca envíes passwords, tokens de acceso o datos personales en la URL.

Cómo evitarlo: usa siempre el body de la petición para datos sensibles. Si necesitas pasar un ID, puedes usarlo en la URL, pero mueve el resto al body o a headers.

Error 6: No gestionar correctamente los timeouts

Un timeout mal configurado puede bloquear tu aplicación. Si pones un timeout de 30 segundos, el usuario se quedará esperando 30 segundos antes de ver un error: demasiado tiempo.

Recomendación: timeouts de 5-10 segundos para peticiones normales. Para operaciones largas, usa polling o webhooks en lugar de esperar una respuesta síncrona.

Error 7: No guardar el estado ante errores

Si una petición falla, ¿pierdes los datos que el usuario acaba de introducir? Eso es una mala experiencia de usuario.

Cómo evitarlo: guarda el estado de la aplicación en memoria o localStorage antes de hacer peticiones. Si algo falla, puedes restaurar los datos sin que el usuario tenga que reintroducirlos.

Error 8: No documentar qué APIs usas y cómo

Si integras 5 APIs distintas y ninguna está documentada, cualquier developer que toque el código en el futuro perderá horas entendiendo cómo funciona todo.

Cómo evitarlo: documenta cada integración con:

• Endpoint y método HTTP
• Qué datos necesitas enviar
• Qué datos recibes
• Qué errores puedes esperar
• Cuál es el rate limit

Error 9: No tener en cuenta el rate limit

Cada API tiene un límite de peticiones por segundo o por día. Si lo superas, la API te bloquea temporalmente. Muchos developers descubren esto cuando su aplicación deja de funcionar en producción.

Cómo evitarlo: implementa un sistema de cola que respete los límites. Si la API permite 100 peticiones por minuto y tú necesitas 500, hazlas en batches con delays.

Error 10: No monitorizar las integraciones en producción

Has implementado la integración, la has probado en desarrollo y funciona bien. Pero en producción, sin monitorización, no sabes si la API está fallando hasta que un usuario te lo reporta.

Cómo evitarlo: implementa logs de cada integración y alertas cuando el ratio de errores supere el 5%. Herramientas como Sentry, Datadog o incluso un sistema simple de logging te pueden salvar de horas de incidentes.

Checklist rápida antes de subir a producción

Antes de lanzar cualquier integración de API, verifica:

• ¿Gestiono correctamente la expiración de tokens?
• ¿Tengo reintentos con backoff exponencial?
• ¿Valido la estructura de la respuesta?
• ¿Tengo timeouts configurados?
• ¿Estoy guardando estado antes de cada petición?
• ¿He documentado la integración?
• ¿He configurado alertas para errores?
• ¿He probado el camino de error (no solo el happy path)?

FAQ: Preguntas frecuentes

¿Cuántas APIs puedo integrar en una web?

No hay un límite fijo, pero cada integración añade complejidad y puntos de fallo. Prioriza las que aporten más valor a tus usuarios.

¿Qué hago si la API que uso cambia su formato de respuesta?

Implementa versionado en tus llamadas a la API y guarda el histórico de cambios. Cuando detectes un cambio, actualiza tu validación y notifica a tu equipo.

¿Es mejor una API REST o GraphQL?

Depende del caso de uso. REST es más simple y cacheable. GraphQL da más flexibilidad, pero añade complejidad. Para la mayoría de proyectos web, REST es suficiente.

¿Tienes un proyecto con integraciones complejas? En Artemis Code trabajamos con conexiones de APIs a diario. Escríbenos a contact@artemiscode.es o visita nuestra página de desarrollo a medida para saber cómo podemos ayudarte.