Límites de uso

Cuando superas un límite, la API responde 429 Too Many Requests con el encabezado Retry-After: los segundos que debes esperar antes de reintentar, como mínimo 1.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{ "status": 429, "title": "Too many requests" }

Qué tiene límite

• Todas las peticiones, por credencial o por IP.
• Escrituras de compra en Storefront: checkout, pagos, comprobantes de pago, cupones, reseñas, cancelaciones y devoluciones tienen un límite más bajo que las lecturas.
• Autenticación: POST /connect/token y el envío de códigos de inicio de sesión.
• Operaciones masivas de Admin: importaciones, exportaciones y actualizaciones por lote se atienden de una en una por tienda. Si envías otra antes de que la anterior responda, recibes 429.

Reintenta

Espera lo que indica Retry-After y repite la petición. Pon un máximo de intentos.

async function withRetryAfter(request: () => Promise<Response>, maxAttempts = 4) {
  for (let attempt = 1; ; attempt += 1) {
    const response = await request();
    if (response.status !== 429 || attempt === maxAttempts) return response;

    const seconds = Number(response.headers.get("retry-after") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

Reintentar un 429 es seguro: la petición rechazada no se ejecutó. Si varios procesos comparten credenciales, usa una cola común para que no reintenten todos a la vez.

Una importación aceptada responde 202 con el id de una operación que corre en segundo plano. Sigue su avance con GET /v1/operations/{id}; volver a enviar el archivo crea otra importación.

Gasta menos peticiones

• Pide páginas grandes: limit=200 en los listados por cursor.
• Cachea lo que cambia poco, como categorías, marcas o zonas.
• Usa webhooks en lugar de consultar cada cierto tiempo.