Gestire i limiti di frequenza

01In una frase #sec_56b85c74

Tre contatori indipendenti governano la frequenza — i dati, le prove, i token — e alcune chiamate ne consumano due alla volta.

02I tre limiti #sec_0a236919

Queste sono valori predefiniti, non costanti: la tua sottoscrizione può avere un limite più alto. Un aumento concesso dall'editore ha effetto dalla richiesta successiva, senza riavvio né ritardo di propagazione.

03Il contatore delle prove si aggiunge, non sostituisce #sec_4b9c7978

Questo è il punto che sorprende di più. Una chiamata a evidence decrementa entrambi i contatori: quello delle prove e quello standard. Un cliente che effettua solo chiamate di prova verrebbe quindi fermato a sessanta al minuto, non a seicento.

La ragione è misurabile: ogni chiamata di prova produce un PDF e lo firma, circa 325 ms di processore e crittografia. Al limite comune, un singolo cliente avrebbe consumato quasi il 40% della macchina; a sessanta al minuto, circa il 4%. Il limite distinto esiste affinché la lentezza di un integratore non diventi la lentezza di tutti.

04Ciò che viene contato, e per chi #sec_f6c8dcbb

Il contatore è collegato al cliente autenticato, non all'indirizzo IP. Due processi che condividono un client_id condividono il suo limite, ovunque essi siano eseguiti; due clienti distinti sulla stessa macchina hanno ciascuno il proprio.

Il punto di chiamata dei token fa eccezione prima dell'autenticazione: non avendo ancora un cliente, conta per indirizzo IP.

Conseguenza pratica: se più integrazioni devono coesistere, assegna a ciascuna il proprio cliente invece di condividere un segreto. Smetteranno di interferire tra loro, e un superamento designerà il colpevole.

05Il rifiuto #sec_7af04e67

Un superamento restituisce 429 Too Many Requests, con un'intestazione Retry-After e un corpo application/problem+json.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "type": "https://docs.reviewit.example/problems/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "The rate limit for this client has been exceeded. Retry after the indicated delay.",
  "instance": "/api/v1/evidence/4821"
}

instance porta il percorso rifiutato: su un'integrazione che chiama più domini, è questo campo che indica quale ha superato il limite.

06Riprovare #sec_41e4809f

Il limite è una finestra fissa di un minuto, non un flusso smorzato. Il contatore riparte da zero all'inizio di ogni minuto, non si ricarica progressivamente.

Aspetta il ritardo indicato da Retry-After. Riprovare prima non fa altro che consumare la finestra successiva, e un cliente che si blocca senza attendere rimane bloccato indefinitamente facendo credere a un guasto.

Non c'è una coda. Una chiamata oltre il limite viene rifiutata immediatamente, non viene messa in attesa. È deliberato: una risposta rapida che dice no è più utile di una risposta lenta che alla fine dice sì, perché lascia al cliente la scelta di rallentare.

07Restare sotto il limite #sec_767baf63

Tre gesti, nell'ordine in cui sono redditizi.

Il primo: conservare il token. Un token vive un'ora; richiederne uno nuovo ad ogni chiamata esaurisce il limite di token — il più basso dei tre — ben prima di quello dei dati.

Il secondo: aumentare la dimensione della pagina piuttosto che moltiplicare le chiamate. Cinquecento elementi in una richiesta costano un token di debito; gli stessi cinquecento in cinque richieste ne costano cinque.

Il terzo: distanziare le prove. Hanno il loro limite specifico e consumano anche lo standard; raggrupparle in raffica è il modo più rapido per scontrarsi con entrambi.

08Da ricordare #sec_2dde19f8

Seicento chiamate al minuto, sessanta per le prove che si aggiungono allo standard, sessanta per i token. Un contatore per cliente autenticato. Un rifiuto immediato, mai una coda. E Retry-After che dice esattamente quanto tempo aspettare.