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. 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 ogni429successivo (per esempio raddoppiandolo), invece di riprovare subito in un ciclo serrato. - Rispettare
Retry-After. Quando la risposta contiene un’intestazioneRetry-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 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.
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.