7 Errores de Integración de APIs REST que Cuestan Dinero a tu Negocio

7 Errores de Integración de APIs REST que Cuestan Dinero a tu Negocio

Tienes Stripe, SendGrid y el CRM integrados. Todo funciona hasta que aparece un cargo duplicado, 200 registros repetidos en el CRM o clientes que no reciben el email de bienvenida.

La causa suele ser la misma: errores de integración que parecían menores y se acumulan en producción. Estos son los 7 más costosos que vemos en proyectos reales, y cómo corregirlos.

Complementa este post con la guía completa de integración de APIs y con 10 errores habituales en REST.

Error 1: No gestionar los HTTP status codes

Muchos desarrolladores solo contemplan 200 OK. Pocos tratan 429 Too Many Requests, 503 Service Unavailable o 401 Unauthorized con reintentos inteligentes.

async function crearUsuario(data, reintentos = 3) {
  for (let i = 0; i < reintentos; i++) {
    const response = await fetch("/api/usuarios", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });

    if (response.ok) return await response.json();

    if (response.status === 429 || response.status === 503) {
      const retryAfter = Number(response.headers.get("Retry-After")) || 2;
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    if (response.status === 401) throw new Error("API_KEY_INVALID");

    throw new Error(`API_ERROR: ${response.status}`);
  }
  throw new Error("MAX_RETRIES_EXCEEDED");
}

Los códigos 429 y 503 suelen ser temporales. Reintenta con backoff, no dispares cien peticiones en el mismo segundo cuando el servicio se recupere.

Error 2: No guardar estado antes de llamar a la API

Si cobras en Stripe, envías email y creas el usuario en el CRM en una sola petición HTTP y algo falla a mitad, no hay transacción global entre sistemas externos.

Patrón recomendado: outbox

Guarda la intención en tu base de datos dentro de una transacción y procesa las APIs con un worker idempotente. Si el worker cae, reintenta sin perder el registro ni duplicar cobros sin control.

Error 3: No usar idempotency keys en POST

Stripe y otras APIs de pago soportan claves de idempotencia. Si el usuario hace doble clic o la red corta después del cobro, sin idempotency puedes cobrar dos veces.

const idempotencyKey = `charge-${customerId}-${orderId}`;

await stripe.charges.create(
  { amount, currency: "eur", customer: customerId },
  { idempotencyKey }
);

Misma clave en reintentos de la misma operación: el proveedor devuelve el mismo resultado sin duplicar.

Error 4: No validar webhooks

Sin validar la firma, cualquiera puede enviarte eventos falsos y marcar pedidos como pagados.

const event = stripe.webhooks.constructEvent(
  req.body,
  req.headers["stripe-signature"],
  process.env.STRIPE_WEBHOOK_SECRET
);

Responde 200 cuando hayas aceptado el evento. Procesa en background si la operación es larga, pero registra el evento antes de perderlo.

Error 5: No respetar rate limits propios

Si necesitas 500 actualizaciones y el proveedor permite 100 por minuto, necesitas cola con throttling. Lanza peticiones en serie o con límite de concurrencia controlado.

Error 6: No renovar tokens OAuth

Access tokens expiran. Si guardas uno durante meses sin refresh, un día la integración deja de funcionar sin aviso.

Renueva con margen (por ejemplo 1 minuto antes de expirar) y ante 401 fuerza un refresh y un solo reintento de la petición original.

Error 7: No hacer logging estructurado

Sin requestId, timestamp y status en logs, cuando un cliente dice “el pago falló” no puedes reconstruir la secuencia.

const requestId = crypto.randomUUID();
console.log(JSON.stringify({ level: "info", requestId, url: endpoint }));

Propaga el mismo requestId en tu API, workers y alertas.

Checklist rápida

• Reintentos con backoff en 429 y 503
• Idempotency keys en operaciones que modifican estado
• Firma de webhooks verificada
• Cola con rate limiting propio
• Refresh automático de tokens
• Logging con request ID

Si respondes “no” a dos o más, tienes riesgo real en producción.

¿Necesitas una integración sin errores?

En Artemis Code hemos integrado Stripe, PayPal, SendGrid, HubSpot y decenas de APIs más. Habla con nosotros para tu proyecto →