Quota e limites de taxa

Uma cobrança por organização

O uso da plataforma é medido por organização, não por chave — todas as chaves da sua organização consomem um orçamento mensal compartilhado e compartilham os rate limits. Uma chave, uma cobrança: AI, maps e design debitam o mesmo medidor da organização.

O orçamento é redefinido em um ciclo de calendário mensal.

O que seu plano inclui

O plano da sua organização define tanto o que uma chave pode acessar quanto o orçamento mensal compartilhado de tokens:

Plan	API surface	Monthly API tokens	Monthly map loads
Free	apenas Basemaps — uma publishable key com scope maps e produto tile	n/a (sem scope ai)	50,000
Pro	plataforma completa (ai, maps, design; browser + server keys)	5,000,000	50,000
Enterprise	plataforma completa	50,000,000	50,000

Todos os planos têm a mesma franquia de map-loads — os planos se diferenciam por tokens, superfície API e recursos. Volumes Enterprise acima da franquia são concedidos como aumentos por organização, não como um nível de plano superior.

Chaves do plano Free servem embeds de basemap, medidos como map loads em vez de tokens. Para acessar as superfícies AI e design, faça upgrade em kaleidr.com/billing. Alterações de plano se aplicam às suas chaves existentes em alguns minutos; não é necessário fazer re-mint — embora uma chave criada no Free seja reconfigurada em scopes na próxima rotação.

O body 429

Uma solicitação que ultrapassaria o limite retorna 429 Too Many Requests com um body plano no nível superior — payloads 429 estruturados não envolvem campos em um objeto detail (apenas 429s com string-detail, como map_load_hard_stop, fazem isso):

{
  "error": "b2b.tokens_exceeded",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 5000000,
  "remaining": 0,
  "reset_at": "2026-10-01T00:00:00Z",
  "reset_in_seconds": 123456
}

Para endpoints de streaming, o limite também aparece durante o stream por meio de um quota SSE event, para que sua UI possa reagir antes que o stream termine.

Consulte Errors — Envelope para a divisão completa entre 429s planos e encapsulados.

Ultrapassando a franquia

O que acontece acima da sua franquia depende do plano, e os dois casos são propositalmente diferentes.

Free para na franquia. Uma solicitação que a ultrapasse retorna 429 map_load_quota_exceeded. Esse limite define o produto de basemap gratuito.

Pro e Enterprise continuam servindo. Um excesso em uma conta paga é uma conversa de billing, não uma indisponibilidade, portanto seus embeds não param no meio do mês — registramos o excesso e fazemos acompanhamento.

Essa tolerância não é ilimitada. Planos pagos param em cinco vezes a franquia com 429 map_load_hard_stop. Nenhum embed normal chega a esse ponto; o teto existe para impedir que alguém que copie uma publishable key do código-fonte da sua página gere uma cobrança ilimitada em seu nome. Pacotes adicionais de map-load aumentam a franquia, e o teto cresce junto.

Se você atinge regularmente a faixa flexível, precisa de mais franquia em vez de um workaround — entre em contato.

Acesso ao basemap

Os designed basemaps fazem parte da sua conta Kaleidr, não são uma tile API pública independente: embeds <kaleidr-map> e o SDK autorizam por meio da sua publishable key (scope maps), e cada map load — abertura de shared-map, visualização publicada/incorporada ou sessão basemap do SDK, aproximadamente 20 tile requests — consome da franquia mensal compartilhada descrita acima. Uso direto de terceiros de tile.kaleidr.com fora de um keyed embed é bloqueado com 429 e este body:

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr account. Kaleidr-hosted maps and embeds are unaffected — see the docs.",
  "docs": "https://docs.kaleidr.com/platform-api/quota-and-rate-limits"
}

O 429 também inclui um header Retry-After: 3600 — não tente novamente antes.

Se você precisa de mais que a franquia, entre em contato — volumes maiores são concedidos por organização, e Enterprise pode servir por um CDN independente.

Rate limits e concorrência

Dois limites ficam à frente da quota, e ambos descartam o excesso com 429 em vez de colocá-lo em fila:

• Requests por minuto, por chave — janela móvel de 60 segundos. Cada chave possui sua própria taxa.
• Streams simultâneos, por organização — solicitações de streaming simultâneas em todas as chaves da organização.

Tente novamente com backoff. Um 429 aqui significa "rápido demais agora"; um 429 contendo meter no body significa que você atingiu o limite mensal.

Como lidar

• Trate 429 como "reduza o ritmo / faça upgrade", não "quebrado". Faça backoff e tente novamente.
• Exiba o evento quota durante o stream na sua UI (orçamento restante).
• Consulte Errors para a tabela completa de status.