Limites de taxa

A RealityConnect API limita a taxa de requisições por organização usando um bucket de tokens por família de rota. Esta página aborda os buckets, os cabeçalhos presentes em toda resposta sujeita a limite de taxa, e o que fazer diante de um 429 Too Many Requests.

---

Buckets

Cada bucket tem uma capacidade (número máximo de tokens, ou seja, o tamanho da rajada) e uma taxa de recarga (tokens adicionados por segundo, ou seja, a taxa sustentada). Uma requisição consome um token; quando o bucket está vazio, a requisição é recusada com 429.

Bucket	Capacidade	Taxa de recarga	Abrange
assets	1000	10/s	RealityAssets, tipos de ativo, categorias de ativo, criação/leitura/listagem/exclusão de objetos de negócio
twin	1000	10/s	Espaço de twin, POIs, zonas, rascunhos
platform	1000	10/s	Site, nó de dados, data bundle, plugins
plan	1000	10/s	Espaço de reality plan, ativos de modelo
library	1000	10/s	Modelos e etiquetas da Asset Library
embed	100	2/s	Emissão de sessão de incorporação
users	1000	10/s	Usuários, grupos, funções, convites
sitefiles	1000	10/s	Arquivos de site

O limite de taxa é por organização: todos os aplicativos OAuth e usuários que agem em nome da mesma organização compartilham um bucket por família.

Cabeçalhos de resposta

Toda resposta sujeita a limite de taxa, bem-sucedida ou não, carrega estes cabeçalhos:

Cabeçalho	Significado
X-RateLimit-Limit	A capacidade do bucket
X-RateLimit-Remaining	Tokens restantes no bucket
X-RateLimit-Reset	Segundos até o bucket ficar cheio novamente
X-RateLimit-Policy	{capacity};w={window}, em que window (segundos) é capacity / refillRate

Somente em 429 Too Many Requests, a resposta também carrega Retry-After (segundos até que pelo menos um token esteja disponível) e este corpo:

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

Lidando com o 429

Recue usando Retry-After em vez de um atraso fixo ou de uma nova tentativa imediata: tentar novamente de imediato contra um bucket vazio só produz outro 429. Para cargas de trabalho sustentadas de alto volume, ritme as requisições para ficar abaixo da taxa de recarga do bucket, em vez de rajadas até a capacidade máxima seguidas da espera pelo reset.

Próximos passos

• Consulte a referência da API para as operações exatas em cada bucket.