Rate limits

Cada API key tiene un límite de 60 peticiones por minuto por defecto. Si necesitas más, escríbenos a soporte@buildnexion.com.

Cuotas

Cabeceras de respuesta

Cada respuesta incluye:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit:     60
X-RateLimit-Remaining: 47
X-RateLimit-Reset:     1716629400

• X-RateLimit-Limit — tu cuota máxima por minuto.
• X-RateLimit-Remaining — llamadas que te quedan en la ventana actual.
• X-RateLimit-Reset — timestamp UNIX en segundos cuando se restablece la cuota.

Respuesta 429

Si superas el límite, la API responde con 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Has superado el límite de 60 peticiones por minuto.",
    "details": { "retry_after_seconds": 23 }
  }
}

Espera el tiempo indicado en retry_after_seconds (o usa X-RateLimit-Reset) y reintenta.

Reintentos con backoff

Ejemplo de helper que reintenta automáticamente:

async function callWithRetry(url, opts, attempt = 0) {
  const res = await fetch(url, opts)
  if (res.status === 429 && attempt < 3) {
    const reset  = Number(res.headers.get('X-RateLimit-Reset')) || 0
    const waitMs = Math.max(1000, reset * 1000 - Date.now())
    await new Promise(r => setTimeout(r, waitMs))
    return callWithRetry(url, opts, attempt + 1)
  }
  return res
}

Buenas prácticas

• Cachea respuestas de lectura cuando puedas (no necesitas pedir la lista de proveedores cada minuto).
• Si necesitas leer muchos datos, paginal con limit=100 en vez de hacer mil peticiones de uno en uno.
• Prefiere webhooks a polling: te llegan los cambios al momento sin consumir cuota.