速率限制

RealityConnect API 按组织对请求进行速率限制，每个路由系列使用一个令牌桶。本页介绍这些桶、每个受速率限制的响应都会携带的标头，以及在遇到 429 Too Many Requests 时该怎么做。

令牌桶

每个桶都有一个容量（最大令牌数，即突发规模）和一个补充速率（每秒新增的令牌数，即持续吞吐量）。每个请求消耗一个令牌；当桶为空时，请求会被拒绝并返回 429。

桶	容量	补充速率	涵盖范围
`assets`	1000	10/s	RealityAsset、资产类型、资产类别、业务对象的创建/读取/列表/删除
`twin`	1000	10/s	Twin 空间、POI、区域、草稿
`platform`	1000	10/s	站点、数据节点、Data Bundle、插件
`plan`	1000	10/s	RealityPlan 空间、模型资产
`library`	1000	10/s	Asset Library 模型和标签
`embed`	100	2/s	Embed 会话签发
`users`	1000	10/s	用户、用户组、角色、邀请
`sitefiles`	1000	10/s	站点文件

速率限制按组织计算：代表同一组织行事的所有 OAuth 应用程序和用户，会共享每个系列的同一个桶。

每个受速率限制的响应，无论成功与否，都会携带以下标头：

标头	含义
`X-RateLimit-Limit`	该桶的容量
`X-RateLimit-Remaining`	桶中剩余的令牌数
`X-RateLimit-Reset`	距离桶再次填满的秒数
`X-RateLimit-Policy`	`{capacity};w={window}`，其中 `window`（秒）等于 `capacity / refillRate`

仅在 429 Too Many Requests 时，响应还会携带 Retry-After（距离至少有一个令牌可用的秒数）以及以下响应体：

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

请使用 Retry-After 来退避，而不是采用固定延迟或立即重试：对着空桶立即重试只会得到另一个 429。对于持续的高流量工作负载，请将请求节奏控制在桶的补充速率以下，而不是先突发到容量上限，再等待重置。