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

# Limiti e quote

Una chiamata API può essere fermata per tre motivi: troppe richieste in poco
tempo, una richiesta troppo grande, oppure credito o budget finiti. Il terzo è
spiegato in [Costi, budget e analytics](/api-costi); qui ci sono gli altri due, e
come scrivere un client che li regge.

## Limiti di frequenza

I limiti valgono per area di lavoro **e per modello**, sommando tutte le chiavi:
creare una chiave in più non li raddoppia, mentre due modelli diversi hanno due
contatori separati.

| Limite                           | Valore |
| -------------------------------- | ------ |
| Richieste al minuto, per modello | 500    |
| Token al minuto, per modello     | 60.000 |

Il minuto è una finestra che scorre, non si azzera allo scoccare del minuto.

Il limite che si incontra per primo è quasi sempre quello sui token, per come
vengono contati. Quando una chiamata parte, Userbot **prenota** i token che
potrebbe usare: una stima del testo che mandi più il tetto della risposta, cioè
`max_tokens` o, se non lo indichi, 16.384. A risposta finita la prenotazione
viene corretta con i token davvero usati.

In pratica, senza `max_tokens` ogni chiamata prenota più di 16.000 token, e sullo
stesso modello ne stanno in volo poco più di tre alla volta. Indicare un
`max_tokens` realistico per il tuo compito è il modo più semplice per farne
passare molte di più.

Oltre il limite ricevi `429` con questo corpo:

```json
{ "message": "Rate limit for public API exceeded" }
```

Le risposte non portano header `X-RateLimit-*` né `Retry-After`: il tuo client
deve gestire l'attesa da solo, come spiegato più sotto.

## Limiti di dimensione

| Limite                   | Valore                                              |
| ------------------------ | --------------------------------------------------- |
| Corpo della richiesta    | 30 MB, allegati compresi                            |
| Messaggi per richiesta   | Nessun tetto fisso                                  |
| Testo complessivo        | La finestra di contesto del modello scelto          |
| Lunghezza della risposta | `max_tokens`, oppure 16.384 token se non lo indichi |
| Strumenti per richiesta  | 128                                                 |

Tutti i messaggi che mandi, più la risposta da generare, devono stare nella
finestra di contesto del modello: oltre, la richiesta fallisce. Se lavori su
documenti lunghi, spezzali e chiama più volte.

Quando la risposta si ferma al tetto, `finish_reason` vale `length`: controllalo
prima di usare il testo, perché vuol dire che è tagliato.

Il limite anti-spam della chat, i 250 messaggi ogni 3 ore per persona, non vale
per l'API.

## Riprovare quando qualcosa va storto

#### Distingui il temporaneo dal definitivo

Si riprovano il `429` senza `code` (frequenza), il `500` e il `503`. Non si
riprovano `400`, `401`, `402`, `403`, `451` e i `429` con un `code` di
budget: sono un corpo da correggere, una chiave da sistemare o un credito da
ricaricare, e aspettare non serve.

#### Riprova con attesa crescente

Raddoppia l'attesa a ogni tentativo (1, 2, 4, 8 secondi) e aggiungi qualche
decimo di secondo casuale. Senza quella variazione, tutti i tuoi processi
ripartono nello stesso istante e si bloccano di nuovo a vicenda.

#### Ferma dopo qualche tentativo

Cinque tentativi bastano. Oltre, registra l'errore e metti la richiesta in
coda per dopo: continuare a insistere non la fa passare.

## Progettare per stare dentro i limiti

**Accoda invece di parallelizzare.** Manda le richieste da una coda con un numero
fisso di processi, non aprendo una chiamata per ogni riga di un file.

**Indica sempre `max_tokens`.** È quello che decide quante chiamate stanno in
volo insieme.

**Raggruppa il lavoro.** Dieci frasi da classificare stanno in una richiesta
sola, con la risposta chiesta in elenco. Per gli embedding, manda una lista di
testi in una chiamata.

**Distribuisci sui modelli.** I contatori sono per modello: due flussi di lavoro
diversi su due modelli non si rubano spazio.

**Metti in cache le risposte stabili.** Se la stessa domanda torna uguale, la
seconda volta non serve chiamare.

**Separa gli ambienti.** Staging e produzione con chiavi diverse ti dicono chi
ha consumato cosa nelle analytics.

Se il tuo carico richiede limiti più alti, scrivi a
[support@userbot.ai](mailto:support@userbot.ai) indicando le richieste e i token
al minuto che ti servono, e su quali modelli.