Limiti di frequenza

La RealityConnect API applica limiti di frequenza alle richieste per organizzazione usando un token bucket per famiglia di route. Questa pagina copre i bucket, gli header presenti in ogni risposta soggetta a limite di frequenza e cosa fare in caso di 429 Too Many Requests.

---

Bucket

Ogni bucket ha una capacità (numero massimo di token, ossia la dimensione del burst) e una velocità di ricarica (token aggiunti al secondo, ossia il throughput sostenuto). Una richiesta consuma un token; quando il bucket è vuoto, la richiesta viene rifiutata con 429.

Bucket	Capacità	Velocità di ricarica	Copre
assets	1000	10/s	RealityAsset, tipi di asset, categorie di asset, creazione/lettura/elenco/eliminazione di oggetti business
twin	1000	10/s	Spazio twin, POI, zone, bozze
platform	1000	10/s	Site, data node, data bundle, plugin
plan	1000	10/s	Spazio reality plan, model asset
library	1000	10/s	Modelli e tag dell’asset library
embed	100	2/s	Emissione di sessioni di embed
users	1000	10/s	Utenti, gruppi, ruoli, inviti
sitefiles	1000	10/s	File di sito

Il limite di frequenza è per organizzazione: tutte le applicazioni OAuth e gli utenti che agiscono per conto della stessa organizzazione condividono un unico bucket per famiglia.

Header di risposta

Ogni risposta soggetta a limite di frequenza, che abbia successo o meno, include questi header:

Header	Significato
X-RateLimit-Limit	La capacità del bucket
X-RateLimit-Remaining	I token rimasti nel bucket
X-RateLimit-Reset	I secondi mancanti prima che il bucket torni pieno
X-RateLimit-Policy	{capacity};w={window}, dove window (in secondi) è capacity / refillRate

Solo su 429 Too Many Requests, la risposta include anche Retry-After (i secondi mancanti prima che almeno un token sia disponibile) e questo corpo:

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "rate_limited"
}

Gestire i 429

Rallenta usando Retry-After invece di un ritardo fisso o di un nuovo tentativo immediato: ritentare subito contro un bucket vuoto produce solo un altro 429. Per carichi di lavoro sostenuti e ad alto volume, scandisci le richieste per restare sotto la velocità di ricarica del bucket, invece di saturarlo fino alla capacità e attendere il reset.

Cosa c’è dopo?

• Consulta il riferimento API per le operazioni esatte incluse in ogni bucket.