# Rate limit e utilizzo Come le richieste vengono conteggiate sul proprio piano, che aspetto ha la risposta 429 e il limite di dimensione di una singola richiesta. **In prospettiva.** Il rate limiting, i tetti di utilizzo e le risposte `402`, `403`, `413` e `429` fanno parte del contratto dell’API ma **non sono ancora applicati**. Questa pagina ne descrive il comportamento, così da poter costruire un client già pronto a gestirli. Qui non viene pubblicata alcuna soglia numerica, perché nessuna è in vigore. PDF Blocks è progettato per degradare in modo controllato sotto carico e per mantenere visibile il proprio utilizzo. Questa pagina spiega come viene misurato l’utilizzo, come si manifesta il rate limiting e come dimensionare le richieste. ## Come viene misurato l’utilizzo L’utilizzo viene misurato per piano e tracciato nella propria [dashboard](https://dashboard.pdfblocks.com). La dashboard fa fede per quanto è stato consumato sul proprio piano, sia per il numero di documenti elaborati sia per il numero di richieste effettuate. Consultarla per monitorare il consumo e per vedere quanto ci si sta avvicinando al volume incluso nel proprio piano. Poiché l’API è *stateless*, ogni richiesta viene misurata singolarmente: non ci sono sessioni né lotti da riconciliare. Un’azione che produce più documenti, come una divisione, conta comunque come una sola richiesta. ## I rate limit e la risposta 429 Quando il rate limiting sarà applicato, alle richieste che superano il volume consentito dal proprio piano verrà risposto con `429 Too Many Requests` e un corpo [problem+json](/docs/api/errors). Un `429` è transitorio: la stessa richiesta andrà a buon fine non appena si rallenta. Conviene costruire i client in modo che lo gestiscano fin dal primo giorno: - **Applicare un backoff esponenziale.** Su un `429`, attendere prima di riprovare e aumentare il ritardo a ogni `429` successivo (per esempio raddoppiandolo), invece di riprovare subito in un ciclo serrato. - **Rispettare `Retry-After`.** Quando la risposta contiene un’intestazione `Retry-After`, attendere almeno quel tempo prima di riprovare, invece di usare un ritardo proprio. - **Aggiungere jitter.** Randomizzare leggermente il backoff, in modo che i worker paralleli non riprovino tutti nello stesso istante. - **Limitare i tentativi.** Rinunciare dopo un numero ragionevole di tentativi e segnalare l’errore, invece di riprovare all’infinito. La stessa strategia di backoff vale per il raro errore di server `5xx`. ## Limiti di dimensione delle richieste Gli upload molto grandi possono essere rifiutati con `413 Payload Too Large`. Quando questo limite sarà applicato, una richiesta il cui corpo supera la dimensione accettata restituirà un corpo [problem+json](/docs/api/errors) e non verrà elaborata. A differenza di un `429`, un `413` non andrà a buon fine riprovando: occorre inviare un file più piccolo. Per le strategie di upload e download in streaming, i timeout e l’elaborazione di documenti di grandi dimensioni, vedere [Lavorare con file di grandi dimensioni](/docs/api/working-with-large-files). ## Risposte legate alla fatturazione Altri due codici riservati riguardano il proprio account anziché la singola richiesta: - **`402 Payment Required`**: una condizione di fatturazione o di quota sul proprio piano. Si risolve dalla [dashboard](https://dashboard.pdfblocks.com). - **`403 Forbidden`**: la chiave è valida ma non è autorizzata a usare la risorsa richiesta. Entrambi compaiono nel catalogo degli [Errori](/docs/api/errors), insieme alla forma completa della risposta.