Rate limiting

Le API Userbot applicano limiti di frequenza per API key per garantire stabilità e fair use dell’infrastruttura condivisa. Se superi il budget di richieste nel periodo corrente, riceverai una risposta 429 Too Many Requests — non un errore permanente, ma un segnale di rallentare e ritentare dopo l’attesa indicata.

Comprendere come funzionano i limiti e come gestire il 429 evita interruzioni in produzione e integrazioni che “martellano” l’API inutilmente.

Header di rate limit

Ogni risposta API — sia di successo (2xx) che di errore client (4xx) — include header che descrivono lo stato del tuo budget:

Monitora x-ratelimit-remaining nel tuo codice: se scende verso zero, puoi rallentare proattivamente le chiamate invece di aspettare il 429.

Risposta 429 Too Many Requests

Quando superi il limite, la risposta ha status 429 e include l’header Retry-After con i secondi di attesa obbligatori prima di ritentare. Non ignorarlo: ritentare subito senza attendere peggiora la situazione e può prolungare il blocco.

Strategia consigliata

Implementa retry con backoff esponenziale, rispettando sempre Retry-After quando presente:

1. Alla prima risposta 429, attendi almeno Retry-After secondi
2. Ai tentativi successivi, aumenta l’attesa (es. Retry-After * attempt)
3. Limita il numero massimo di retry (es. 3) e fallisci gracefully se il limite persiste

Esempio in JavaScript:

1
async function callWithRetry(fn, maxRetries = 3) {
2
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
3
    try {
4
      return await fn();
5
    } catch (err) {
6
      if (err.status === 429 && attempt < maxRetries) {
7
        const retryAfter = err.retryAfter || 5;
8
        const wait = retryAfter * 1000 * attempt;
9
        await new Promise((r) => setTimeout(r, wait));
10
        continue;
11
      }
12
      throw err;
13
    }
14
  }
15
}

Cosa evitare

• Loop REST che chiamano l’API in rapida successione senza pausa
• Retry immediati su 429 senza leggere Retry-After
• Polling aggressivo — preferisci webhook per aggiornamenti in tempo reale invece di GET ripetuti

Per errori di autenticazione (401, 403) non ha senso ritentare: correggi le credenziali prima. Vedi Codici di errore.