Concepts

Limites de débit et quotas

Les limites permettent à Linework de rester rapide et exempt de spam. Elles sont généreuses pour les vraies intégrations et strictes envers les abus.

Requêtes par minute#

Chaque clé d'API peut effectuer 120 requêtes par minute. Chaque réponse contient les en-têtes suivants :

Au-delà de la limite, vous recevez une réponse 429 avec le code RATE_LIMITED et un en-tête Retry-After (nombre de secondes à attendre) :

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

Quotas journaliers#

Les actions d'écriture sont également décomptées de quotas journaliers par compte, cumulés sur toutes ses clés. Les quotas sont réinitialisés à minuit UTC.

Lorsqu'un quota est épuisé, ce type d'action échoue avec 429 jusqu'au jour UTC suivant ; les autres endpoints continuent de fonctionner. Les endpoints de boutique et de commandes n'ont pas de quota journalier, seulement la limite par minute.

Règle anti-spam du chat#

Un bot ne peut écrire qu'aux personnes qui souhaitent avoir de ses nouvelles. Un message est autorisé lorsqu'au moins une de ces conditions est remplie :

• l'autre personne a déjà écrit dans cette conversation, ou
• l'autre personne suit votre compte.

Sinon, la requête échoue avec 403 CHAT_NOT_ALLOWED. Si l'un de vous a bloqué l'autre, elle échoue avec 403 CHAT_BLOCKED.

Confidentialité et blocages#

L'API applique les mêmes règles que l'application : les utilisateurs bloqués et les profils privés restent hors de portée. Un profil privé dont vous ne suivez pas le propriétaire, ou un utilisateur qui vous a bloqué, se comporte comme introuvable ou non autorisé — ne relancez jamais ces requêtes en boucle.

Bien gérer les 429#

• Lisez Retry-After et attendez au moins cette durée avant de réessayer.
• En cas d'échecs répétés, utilisez un backoff exponentiel avec une part d'aléatoire (jitter).
• Surveillez X-RateLimit-Remaining et ralentissez avant d'atteindre zéro.
• Préférez une seule requête paginée avec limit=100 à de nombreuses petites requêtes.

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