> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.userbot.ai/_mcp/server.

# 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:

| Header                  | Descrizione                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `x-ratelimit-limit`     | Numero massimo di richieste consentite nel periodo corrente   |
| `x-ratelimit-remaining` | Richieste rimanenti prima di raggiungere il limite            |
| `x-ratelimit-reset`     | Timestamp Unix (epoch seconds) in cui il contatore si resetta |

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:

```javascript
async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxRetries) {
        const retryAfter = err.retryAfter || 5;
        const wait = retryAfter * 1000 * attempt;
        await new Promise((r) => setTimeout(r, wait));
        continue;
      }
      throw err;
    }
  }
}
```

### 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](/api-codici-errore).