Conceptos

Límites de solicitudes y cuotas

Los límites mantienen Linework rápido y libre de spam. Son generosos con las integraciones reales y estrictos con los abusos.

Solicitudes por minuto#

Cada clave de API puede hacer 120 solicitudes por minuto. Todas las respuestas incluyen estos headers:

Si superas el límite, recibes un 429 con el código RATE_LIMITED y un header Retry-After (segundos que debes esperar):

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry later" } }

Cuotas diarias#

Las acciones de escritura también cuentan para cuotas diarias por cuenta, sumadas entre todas sus claves. Las cuotas se reinician a medianoche UTC.

Cuando se agota una cuota, ese tipo de acción falla con 429 hasta el siguiente día UTC; los demás endpoints siguen funcionando. Los endpoints de tienda y pedidos no tienen cuota diaria, solo el límite por minuto.

Regla antispam del chat#

Un bot solo puede escribir a las personas que quieren saber de él. Un mensaje está permitido cuando se cumple al menos una de estas condiciones:

• la otra persona ya ha escrito en esa conversación, o
• la otra persona sigue tu cuenta.

En caso contrario, la solicitud falla con 403 CHAT_NOT_ALLOWED. Si uno de los dos ha bloqueado al otro, falla con 403 CHAT_BLOCKED.

Privacidad y bloqueos#

La API sigue las mismas reglas que la aplicación: los usuarios bloqueados y los perfiles privados quedan fuera de tu alcance. Un perfil privado cuyo propietario no sigues, o un usuario que te ha bloqueado, se comporta como si no existiera o no estuviera permitido: nunca repitas estas solicitudes en bucle.

Gestionar bien el 429#

• Lee Retry-After y espera al menos ese tiempo antes de reintentar.
• Usa backoff exponencial con algo de jitter aleatorio cuando los fallos se repitan.
• Vigila X-RateLimit-Remaining y reduce el ritmo antes de llegar a cero.
• Es preferible una solicitud paginada con limit=100 a muchas pequeñas.

async function call(url, options = {}, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, {
      ...options,
      headers: { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`, ...options.headers },
    });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") || 2 ** i);
    await new Promise((r) => setTimeout(r, (wait + Math.random()) * 1000));
  }
  throw new Error("Still rate limited");
}

import os, random, time, requests

API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"

def call(method, path, tries=5, **kw):
    for i in range(tries):
        r = s.request(method, API + path, timeout=30, **kw)
        if r.status_code != 429:
            return r
        wait = float(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait + random.random())
    raise RuntimeError("Still rate limited")