Limiti di frequenza

I limiti sono conteggiati per chiave su una finestra scorrevole di un minuto. Valori predefiniti: 600 richieste al minuto per le chiavi di area di lavoro, 1200 per le chiavi partner; il tuo piano può impostare valori diversi e il limite effettivo è sempre negli header della risposta.

Header

Ogni risposta porta con sé lo stato corrente:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 273
X-RateLimit-Reset: 1755081600

• X-RateLimit-Limit — la capacità della finestra per questa chiave.
• X-RateLimit-Remaining — le richieste rimaste nella finestra corrente.
• X-RateLimit-Reset — l'ora Unix (in secondi) in cui la finestra si libera.

Oltre il limite, l'API risponde 429 con Retry-After:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded, retry later",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Retry-After: 12

La finestra scorre

Il contatore non si azzera allo scoccare del minuto: un picco alle 10:00:55 pesa ancora sulla finestra alle 10:01:05. Progetta per un ritmo costante, invece che per picchi allineati al minuto.

Anche le richieste rifiutate vengono conteggiate: un ciclo di tentativi serrato sul 429 non fa che tenere la chiave bloccata.

Un nuovo tentativo fatto bene

async function withRateLimit(request) {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await request();
    if (response.status !== 429) return response;

    const wait = Number(response.headers.get("retry-after") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, wait * 1000 + attempt * 250));
  }
  throw new Error("Rate limit retries exhausted");
}

Rispetta Retry-After invece di tirare a indovinare, aggiungi del jitter perché i worker paralleli non riprovino tutti insieme, e poni un tetto al numero di tentativi.

Restare sotto il limite

• Tieni d'occhio X-RateLimit-Remaining e rallenta prima di arrivare a zero.
• Usa POST /links/bulk: una sola richiesta crea fino a 100 link.
• Preferisci i webhook al polling: gli eventi ti arrivano in pochi secondi e non consumano alcuna richiesta.