PDF Blocks
Aprire la pagina

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 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. Per questi non viene pubblicata alcuna soglia numerica, perché nessuna è in vigore. I limiti di dimensione delle richieste fanno eccezione: sono già applicati, e il limite è pubblicato più sotto.

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. 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. 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

Ogni piano limita la dimensione di un singolo documento in input: 5 MB su Free, 10 MB su qualsiasi altro piano (vedere Prezzi). Una richiesta il cui corpo supera tale limite viene rifiutata con 413 Payload Too Large e restituisce un corpo problem+json senza essere elaborata. A differenza di un 429, un 413 non andrà a buon fine riprovando: inviare un file più piccolo, oppure chiederci di alzare il limite per il proprio account se serve regolarmente di più.

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.
  • 403 Forbidden: la chiave è valida ma non è autorizzata a usare la risorsa richiesta.

Entrambi compaiono nel catalogo degli Errori, insieme alla forma completa della risposta.