Concetti

Rate limit e quote

I limiti mantengono Linework veloce e libero dallo spam. Sono generosi per le integrazioni reali e severi con gli abusi.

Richieste al minuto#

Ogni chiave API può fare 120 richieste al minuto. Ogni risposta include questi header:

Oltre il limite ricevi 429 con codice RATE_LIMITED e un header Retry-After (secondi da attendere):

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" } }

Quote giornaliere#

Le azioni di scrittura contano anche per le quote giornaliere per account, sommate su tutte le sue chiavi. Le quote si azzerano a mezzanotte UTC.

Quando una quota è esaurita, quel tipo di azione fallisce con 429 fino al giorno UTC successivo; gli altri endpoint continuano a funzionare. Gli endpoint dello store e degli ordini non hanno quote giornaliere, solo il limite al minuto.

Regola anti-spam della chat#

Un bot può scrivere solo alle persone che vogliono ricevere suoi messaggi. Un messaggio è consentito quando è vera almeno una di queste condizioni:

• l'altra persona ha già scritto in quella conversazione, oppure
• l'altra persona segue il tuo account.

Altrimenti la richiesta fallisce con 403 CHAT_NOT_ALLOWED. Se uno dei due ha bloccato l'altro, fallisce con 403 CHAT_BLOCKED.

Privacy e blocchi#

L'API segue le stesse regole dell'app: gli utenti bloccati e i profili privati restano irraggiungibili. Un profilo privato di cui non segui il proprietario, o un utente che ti ha bloccato, si comporta come se non esistesse o non fosse consentito: non ritentare mai queste richieste in un ciclo.

Gestire bene il 429#

• Leggi Retry-After e attendi almeno quel tempo prima di ritentare.
• In caso di errori ripetuti usa un backoff esponenziale con un po' di jitter casuale.
• Tieni d'occhio X-RateLimit-Remaining e rallenta prima di arrivare a zero.
• Preferisci una sola richiesta paginata con limit=100 a tante richieste piccole.

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")