Rate limiting

Pickwise Public API aplica rate limiting por API Key para proteger la infraestructura y asegurar uso justo. Toda request cuenta contra el contador de tu key.

Límites actuales

Ventana	Límite por defecto
Por minuto	60 requests
Por día	10 000 requests

• La ventana por minuto es sliding — no se resetea cada minuto exacto, sino que cuenta las últimas 60 segundos.
• El límite aplica a todos los endpoints de la API (batch y single cuentan igual por request).
• Si necesitás límites más altos, contactá a soporte@lubee.com.ar.

Batch es tu amigo

Una request batch de 200 productos cuenta como 1 contra el rate limit, no como 200. Para cargas grandes, preferí los endpoints /products/batch y /orders/batch.

Headers en cada respuesta

Toda respuesta (exitosa o no) incluye headers informativos para que puedas monitorear el uso:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1709827200

Header	Significado
X-RateLimit-Limit	Límite máximo por minuto asignado a tu key.
X-RateLimit-Remaining	Requests restantes en la ventana actual.
X-RateLimit-Reset	Timestamp Unix (segundos) en que se resetea el contador.

Úsalos para reducir el ritmo proactivamente antes de llegar al límite.

Error 429

Cuando excedés el límite, recibís:

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Límite de requests excedido (60/min). Reintente en 45 segundos.",
    "retryAfter": 45
  },
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

• retryAfter en segundos: cuánto esperar antes de reintentar.
• Respetá ese valor. Reintentar antes solo suma más requests al contador.

Backoff exponencial

Cuando recibís 429 (o errores 5xx), implementá retry con backoff exponencial. Usá retryAfter como primera opción; si no está presente, usá tu propio cálculo.

curl

# No hay manera robusta de hacer backoff en curl puro — usar wrapper en shell
for i in 1 2 3; do
  response=$(curl -sS -w "\n%{http_code}" \
    -X POST https://api-{CLIENTE}.pickwise.com.ar/api/v1/public/products \
    -H "Authorization: Bearer pk_live_xxxx" \
    -H "Content-Type: application/json" \
    -d '{...}')
  code=$(echo "$response" | tail -1)
  if [ "$code" != "429" ] && [ "${code:0:1}" != "5" ]; then
    echo "$response" | head -n -1
    break
  fi
  sleep $((2 ** i))
done

Node.js

async function callWithBackoff(url, init, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, init);

    if (res.status === 429) {
      const body = await res.json().catch(() => ({}));
      const retryAfter = body?.error?.retryAfter
        ?? Number(res.headers.get('Retry-After'))
        ?? Math.pow(2, attempt);
      await sleep(retryAfter * 1000);
      continue;
    }

    if (res.status >= 500) {
      await sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    return res;
  }
  throw new Error('Max retries exceeded');
}

const sleep = (ms) => new Promise(r => setTimeout(r, ms));

const res = await callWithBackoff(
  'https://api-{CLIENTE}.pickwise.com.ar/api/v1/public/products',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PICKWISE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ externalId: 'P1', sku: 'SKU1', name: 'Prod 1', stock: 10 })
  }
);

PHP

<?php
function callWithBackoff(string $url, array $payload, int $maxRetries = 5): string {
  for ($attempt = 0; $attempt < $maxRetries; $attempt++) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer ' . getenv('PICKWISE_API_KEY'),
      'Content-Type: application/json'
    ]);
    $response = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code === 429) {
      $body = json_decode($response, true);
      $retryAfter = $body['error']['retryAfter'] ?? pow(2, $attempt);
      sleep($retryAfter);
      continue;
    }

    if ($code >= 500) {
      sleep(pow(2, $attempt));
      continue;
    }

    return $response;
  }
  throw new Exception('Max retries exceeded');
}

Estrategias para minimizar 429

Preferí batch para cargas grandes

POST /products/batch (hasta 200 items) y POST /orders/batch (hasta 50) reducen drásticamente la cantidad de requests. Una sync completa de 10.000 productos = 50 requests en batch vs 10.000 en single.

Delta sync en lugar de full sync

Usá GET /products?updated_since=<ISO> y GET /orders?updated_since=<ISO> para traer solo lo que cambió desde la última sync. Ver guía de productos y guía de órdenes.

Webhooks en lugar de polling

Si estás consultando órdenes repetidamente para detectar cambios de estado, configurá un webhook. Te notificamos en tiempo real sin que consumas rate limit.

Respetá Retry-After

Si el Retry-After dice 45 segundos y reintentás a los 10, te van a seguir rechazando. Solo estás consumiendo capacidad de tu key.

Aumentar el límite

Si tu volumen legítimo supera los 60 req/min (ej: sincronización inicial de un catálogo de 100k productos), contactanos a soporte@lubee.com.ar. Podemos:

• Subir el límite permanentemente para tu key.
• Aprobar un “burst” temporal para una ventana de migración.
• Sugerir el endpoint batch si todavía no lo estás usando.

Siguientes guías

Manejo de errores 429 junto con otros códigos y su estrategia de retry.

Idempotencia Retry seguro con `X-Idempotency-Key`.