Rate Limits

The RealityConnect API rate-limits requests per organization using a token bucket per route family. This page covers the buckets, the headers every rate-limited response carries, and what to do on 429 Too Many Requests.

---

Buckets

Each bucket has a capacity (maximum tokens, i.e. burst size) and a refill rate (tokens added per second, i.e. sustained throughput). A request consumes one token; when the bucket is empty, the request is rejected with 429.

Bucket	Capacity	Refill rate	Covers
assets	1000	10/s	RealityAssets, asset types, asset categories, business object create/read/list/delete
twin	1000	10/s	Twin space, POIs, zones, drafts
platform	1000	10/s	Site, data node, data bundle, plugins
plan	1000	10/s	Reality plan space, model assets
library	1000	10/s	Asset library models and tags
embed	100	2/s	Embed session issuance
users	1000	10/s	Users, groups, roles, invitations
sitefiles	1000	10/s	Site files

Rate limiting is per organization: all OAuth applications and users acting on behalf of the same organization share one bucket per family.

Response headers

Every rate-limited response, successful or not, carries these headers:

Header	Meaning
X-RateLimit-Limit	The bucket’s capacity
X-RateLimit-Remaining	Tokens left in the bucket
X-RateLimit-Reset	Seconds until the bucket is full again
X-RateLimit-Policy	{capacity};w={window}, where window (seconds) is capacity / refillRate

On 429 Too Many Requests only, the response also carries Retry-After (seconds until at least one token is available) and this body:

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

Handling 429

Back off using Retry-After rather than a fixed delay or immediate retry: retrying immediately against an empty bucket only produces another 429. For sustained high-volume workloads, pace requests to stay under the bucket’s refill rate rather than bursting to capacity and waiting out the reset.

What’s next?

• See the API reference for the exact operations under each bucket.