Cotas e limites de taxa

A Kaleidr limita o uso de duas maneiras diferentes, e ambas retornam o status HTTP 429:

• Cota é o quanto sua organização pode usar durante um período de cobrança. Quando ela se esgota, é preciso aguardar a renovação do período ou adicionar mais recursos.
• Limites de taxa determinam a velocidade das chamadas. Ao atingir um limite, reduza o ritmo por alguns segundos.

O corpo da resposta indica qual limite foi atingido. Esta página apresenta os formatos de resposta, a cobrança de cada chamada e como tratar cada situação.

Os dois saldos de uso

O uso é contabilizado por organização em dois saldos.

Saldo	O que o consome	Free	Pro	Enterprise
Créditos de IA	Respostas do chat, consultas de locais, buscas de endereços e análises de design	500,000 por período	5,000,000 por período	Personalizado, definido em contrato
Carregamentos de mapa	Cada sessão Tile e cada visualização de um mapa publicado ou incorporado	50,000 por período	50,000 por período	Mesma franquia básica; volumes maiores definidos em contrato

Três aspectos desses saldos costumam gerar confusão:

• Os créditos de IA compõem um único saldo para toda a organização. Suas chaves de API usam os mesmos créditos de IA consumidos pela sua equipe nos aplicativos da Kaleidr. Não há um orçamento separado para a API: todas as chaves compartilham esse saldo.
• O período corresponde ao seu período de cobrança. Em uma assinatura paga, é o ciclo mensal iniciado no dia da contratação. Sem assinatura, vale o mês do calendário. Os períodos são renovados à meia-noite, no horário do leste dos Estados Unidos.
• Os pacotes aumentam o limite. Pacotes comprados de créditos de IA e carregamentos de mapa são adicionados à franquia do plano, e o campo limit das respostas já os inclui.

Alterações de plano passam a valer para as chaves existentes em poucos minutos. Não é necessário criar novas chaves.

Como cada chamada é cobrada

Chamada	Saldo	Cobrança
POST /chat/control/stream, /chat/summary/stream, /chat/button/stream, /spot/overview/stream	Créditos de IA	Os tokens usados pela resposta, incluindo entrada e saída. Consulte Como um fluxo é cobrado.
POST /chat/control/route	nenhum	Sem cobrança. Uma reserva é feita durante o planejamento da rota e sempre liberada.
POST /spot	Créditos de IA	Tarifa fixa por chamada, com ou sem resultados: a tarifa de /retrieval/poi/enrich quando want inclui content ou photos e o conteúdo é obtido para esta chamada; caso contrário, a tarifa de /retrieval/geocode/forward quando inclui address. Conteúdo já obtido para uma solicitação anterior não é cobrado. Uma chamada apenas para locais, regiões e contornos é gratuita.
GET /retrieval/poi/enrich	Créditos de IA	Tarifa fixa por chamada, cobrada mesmo quando nenhum conteúdo é encontrado.
GET /retrieval/geocode/forward	Créditos de IA	Tarifa fixa menor por chamada, mesmo sem resultados. Não há cobrança se a própria consulta falhar.
POST /design/analyze	Créditos de IA	Tarifa fixa por chamada bem-sucedida. Sem cobrança quando a chamada falha.
POST /design/apply-direct, GET /design/styles, /design/samples, /design/themes	nenhum	Sem cobrança.
POST /sdk/sessions para chat, editor, viewer	nenhum	Sem cobrança.
POST /sdk/sessions para tile	Carregamentos de mapa	Um carregamento de mapa por troca.
POST /sdk/share-sessions	nenhum	Sem cobrança. As chamadas de chat feitas com a sessão são cobradas do proprietário do mapa.
POST /inference-api/vendor/mapping/propose, a proposta de mapeamento da API de envio de dados comerciais	Créditos de IA	Os tokens usados pela proposta. A chamada usa o login de uma conta, não uma chave de API. Quando os créditos se esgotam, retorna 429 quota_exceeded; há também um limite específico de 30 propostas por conta por hora, e os dois erros 429 têm corpos diferentes. Enviar, publicar, despublicar e excluir dados não gera cobrança.

Consulte seu consumo e limites atuais em kaleidr.com/billing.

Como um fluxo é cobrado

Uma chamada de streaming só tem seu custo definido quando termina. Por isso, a cobrança ocorre em duas etapas:

1. Reserva. Quando a solicitação é aceita, um número fixo de créditos é reservado do saldo. Se o saldo não for suficiente para a reserva, a solicitação é recusada com quota_exceeded antes que qualquer resposta seja gerada. Portanto, mesmo uma chamada que custaria menos precisa ter créditos disponíveis suficientes para iniciar.
2. Liquidação. Quando o fluxo termina, a reserva é substituída pela cobrança real: os tokens usados pela resposta. O valor real pode ser maior ou menor que a reserva.

Se você interromper um fluxo, ou ele falhar antes de concluir a resposta, não será possível saber a quantidade exata de tokens; a cobrança será estimada:

Fluxo	Cobrança quando termina sem concluir
/chat/control/stream	O maior valor entre: uma estimativa da conversa enviada (as mensagens user e assistant na solicitação) e uma estimativa do texto já transmitido, contabilizada até o valor reservado. Esse valor pode superar a reserva.
/chat/summary/stream, /chat/button/stream, /spot/overview/stream	Uma estimativa do texto já transmitido, nunca superior à reserva.

Portanto, encerrar um fluxo de chat antecipadamente não torna gratuita uma conversa longa: a solicitação será cobrada pelo menos pelo seu próprio tamanho, mesmo que você leia muito pouco da resposta. Mantenha as solicitações pequenas e envie apenas as interações necessárias para a próxima resposta. Consulte Leitura do fluxo.

Se um limite for atingido durante a execução de um fluxo, ele não será interrompido. A verificação ocorre na admissão; a próxima solicitação será recusada.

Uma solicitação recusada não é cobrada. Quando uma solicitação é recusada antes do processamento (por limite de taxa ou concorrência, erro de validação ou corpo acima do tamanho máximo), ela não mantém créditos de IA reservados nem ocupa uma vaga de concorrência. É possível tentar novamente sem pagar pela recusa.

Limite de consumo por chave

Uma chave pode ter um teto mensal (monthly_cap_tokens, configurado pela API de gerenciamento de chaves). Ele limita a quantidade de créditos de IA da organização que essa chave pode consumir em um período. O saldo da organização continua sendo o limite máximo.

Uma solicitação que ultrapassaria o teto de uma chave é recusada com o mesmo corpo quota_exceeded, mas limit e used indicam os valores da chave, e não os do saldo compartilhado.

Cota excedida

HTTP/1.1 429 Too Many Requests
Retry-After: 1296000
Content-Type: application/json

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "product": "b2b",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 4999100,
  "remaining": 900,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

Campo	Significado
error	Neste caso, sempre quota_exceeded. Use este campo para decidir o fluxo de tratamento.
detail	Uma frase destinada ao usuário. Não faça a análise automática de seu texto.
product, meter	Identificam o contador de créditos de IA da API. Para chaves da plataforma, são sempre b2b e b2b.tokens.
tier	O plano da sua organização.
limit, used, remaining	Os valores de créditos do saldo compartilhado ou, se a chamada foi recusada por um limite específico da chave, os valores dessa chave. remaining pode ser maior que zero: a chamada foi recusada porque não havia saldo suficiente para a reserva temporária.
reset_at	O fim do período, como um registro de data e hora ISO 8601 com deslocamento de fuso horário. Use este valor para informar ao usuário quando o serviço será retomado.
period	month.
reset_in_seconds	Segundos até reset_at, o fim do período em que o saldo é redefinido (seu ciclo de assinatura ou, caso não exista, o mês do calendário). O cabeçalho Retry-After contém o mesmo número.

O corpo é plano: os campos ficam no nível superior, e não dentro de um objeto detail.

Com um token de sessão

O corpo acima é recebido por uma chave de servidor ou chave legada. Uma solicitação feita com um token de sessão é executada no navegador de um visitante; por isso, a recusa não divulga o plano, o consumo nem o limite da organização. Isso vale tanto para uma sessão obtida por uma chave publicável quanto para uma sessão de visitante de um mapa publicado.

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "meter": "b2b.tokens",
  "reset_at": "2026-11-01T04:00:00+00:00",
  "reset_in_seconds": 1296000
}

Campo	Chave de servidor ou chave legada	Token de sessão
error, detail	Sim	Sim
meter	Sim	Sim
reset_at, reset_in_seconds	Sim	Sim
product, period	Sim	Não
tier	Sim	Não
limit, used, remaining	Sim	Não

O status, o cabeçalho Retry-After e o significado são iguais. No código do navegador, verifique error e exiba reset_at; não tente ler limit, used nem remaining. Para mostrar os números de consumo, consulte-os no seu backend com uma chave de servidor ou em kaleidr.com/billing.

Se o corpo mostrar used: 0 apesar de você saber que a organização esteve ativa, a API não conseguiu ler o consumo e recusou a chamada por segurança. Tente novamente após alguns segundos, em vez de aguardar até reset_at.

Limites de taxa e concorrência

Três limites são aplicados antes de cada chamada em execução. Cada um recusa imediatamente o excedente; nada é colocado em fila.

Limite	Contabilizado por	O que abrange
Solicitações por minuto	Chave	Uma janela móvel de 60 segundos para todas as chamadas em execução com a chave e com todas as sessões obtidas dela. Todos os visitantes de um site que usa uma única chave publicável compartilham esse orçamento.
Trocas de sessão por minuto	Chave	Chamadas para POST /sdk/sessions. Orçamento separado, de modo que montar componentes incorporados não consome as chamadas de execução.
Solicitações simultâneas	Organização	Chamadas em andamento ao mesmo tempo em todas as chaves da organização. Um fluxo conta enquanto permanecer aberto.

O limite de solicitações por minuto de uma chave não pode ser editado na página de chaves de API nem pela API de gerenciamento de chaves. Se o seu tráfego precisar de uma taxa maior, entre em contato.

Todas essas recusas têm o mesmo formato de corpo e o mesmo cabeçalho:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{ "error": "rate_limited", "detail": "API key rate limit exceeded. Slow down." }

error	Significado	O que fazer
rate_limited	O orçamento de solicitações por minuto ou de trocas de sessão da chave se esgotou.	Aguarde os segundos indicados em Retry-After e tente novamente. Adicione uma variação aleatória ao intervalo.
org_overloaded	Sua organização tem chamadas demais em andamento.	Aguarde uma chamada aberta terminar e tente novamente. Encerre os fluxos que não forem mais necessários.
b2b_overloaded	A API atingiu a capacidade para todos os usuários.	Aguarde os segundos de Retry-After e tente novamente com espera progressiva.
limiter_unavailable	O limitador de taxa não conseguiu responder.	Tente novamente em breve. Reduzir a taxa de chamadas não ajuda, pois o problema não é seu ritmo de uso.
visitor_limit_reached	Um visitante do chat de um mapa publicado fez solicitações demais por minuto ou por dia.	Mostre uma mensagem solicitando que tente novamente mais tarde. Consulte Chat em um mapa publicado.

As solicitações também são limitadas na borda da rede, por endereço IP e por credencial. Uma solicitação bloqueada ali não recebe nenhum dos corpos JSON descritos nesta página. Trate uma resposta 4xx sem um corpo da Kaleidr como um sinal para reduzir a frequência e tentar mais tarde.

Carregamentos de mapa

Um carregamento de mapa é contabilizado sempre que um mapa Kaleidr é inicializado para um visitante:

• cada troca de sessão para product: "tile", incluindo a renovação pelo SDK e cada nova montagem do elemento;
• cada visualização de um mapa publicado ou incorporado.

A troca de sessão do Editor incorporado não conta como carregamento de mapa. Em vez disso, suas solicitações de mapa-base feitas com a chave publicável (estilo, sprites e fontes) são contabilizadas em lote: a cada 20 solicitações feitas pela organização em uma hora, um carregamento de mapa é adicionado posteriormente. Elas nunca são recusadas por ultrapassar o limite. Os dados de mosaicos do mapa em si não são contabilizados.

Todos os planos param ao atingir sua franquia. Quando o saldo termina, o próximo carregamento é recusado e não contabilizado. Não existe faixa de tolerância nos planos pagos; um pacote de carregamentos adquirido aumenta o limite imediatamente.

Na troca de sessão, a recusa é a seguinte:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{ "detail": "map_load_quota_exceeded" }

Esse corpo vem encapsulado em detail, ao contrário do corpo plano de cota acima, e não tem cabeçalho Retry-After. Tentar novamente não ajuda até que o período seja reiniciado ou que um pacote seja adicionado. Na página, o componente Tile incorporado não inicia, e o SDK registra kaleidr session exchange failed (429).

Solicitações diretas de mosaicos

O servidor de mosaicos do mapa-base não é uma API pública de mosaicos. A forma compatível de exibir um mapa-base Kaleidr é usar o produto Tile. Uma solicitação para tile.kaleidr.com que não venha de um componente Kaleidr incorporado com chave publicável válida em uma origem permitida é recusada:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Cache-Control: no-store
Content-Type: application/json

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr publishable key. Mint a free one at kaleidr.com/api-keys and pass it as ?key= from an allowed origin. Kaleidr-hosted maps and embeds are unaffected.",
  "docs": "https://docs.kaleidr.com/get-an-api-key"
}

Essa resposta vem do servidor de mosaicos, não da API da plataforma; por isso, usa message onde a API usa detail. Uma chave nova ou editada pode levar alguns minutos até ser aceita para mosaicos.

Evento quota em um fluxo

Um fluxo de chat informa o saldo depois de ter sido cobrado. O evento quota é o último evento do fluxo, enviado após end ou error:

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

Esse é o evento de um fluxo consultado com uma chave de servidor ou chave legada. Em um fluxo acessado com um token de sessão (obtido por uma chave publicável ou pela sessão de visitante de um mapa publicado), o evento não inclui o plano nem valores numéricos:

event: quota
data: {"type": "quota", "meter": "b2b.tokens", "reset_at": "2026-11-01T04:00:00+00:00"}

Campo	Chave de servidor ou chave legada	Token de sessão
type, meter, reset_at	Sim	Sim
product, period	Sim	Não
tier	Sim	Não
used, limit	Sim	Não

Com uma chave de servidor, use o evento para atualizar um indicador de consumo sem fazer uma segunda solicitação. Há três limitações:

• Não existe um campo remaining. Calcule limit - used.
• O envio é feito em regime de melhor esforço. Um fluxo pode terminar sem esse evento; não espere por ele.
• O evento informa, mas não avisa previamente. Nunca chega no meio de uma resposta e não pode interromper um fluxo.

Para recebê-lo, continue a leitura até o fechamento do corpo da resposta. Um cliente que para em end não o recebe.

Como tratar 429 no código

Leia o corpo antes de decidir. O status, sozinho, não informa se você deve tentar novamente.

Resposta recebida	Tentar novamente?	Quando
error: "quota_exceeded"	Não	Após reset_at, depois de adicionar créditos ou aumentar o teto da chave. Mostre uma mensagem de limite atingido.
error: "rate_limited", "org_overloaded", "b2b_overloaded", "limiter_unavailable"	Sim	Após os segundos de Retry-After, com variação aleatória, no máximo algumas tentativas.
error: "visitor_limit_reached"	Não	Mais tarde; informe o visitante.
detail: "map_load_quota_exceeded"	Não	Após a renovação do período ou a adição de um pacote de carregamentos de mapa.
error: "tile_access_restricted"	Não	Corrija a incorporação: use o produto Tile com chave publicável em uma origem permitida.

const RETRYABLE = new Set(['rate_limited', 'org_overloaded', 'b2b_overloaded', 'limiter_unavailable']);

async function callKaleidr(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status !== 429) return res;

  const body = await res.json().catch(() => ({}));
  if (RETRYABLE.has(body.error) && attempt < 3) {
    const seconds = Number(res.headers.get('retry-after')) || 5;
    await new Promise((resolve) => setTimeout(resolve, (seconds + Math.random()) * 1000));
    return callKaleidr(url, init, attempt + 1);
  }

  const error = new Error(body.error || body.detail || 'rate limited');
  error.status = 429;
  error.code = body.error || body.detail;
  error.resetAt = body.reset_at; // present for quota_exceeded
  throw error;
}

Em um navegador, o cabeçalho Retry-After pode ser lido pelo JavaScript nas respostas da API da plataforma.

Páginas relacionadas

• Erros: todos os status e códigos.
• Contrato SSE: onde aparece o evento quota em um fluxo.
• Leitura do fluxo: clientes completos com tratamento de tentativas e tempos limite.
• Obter uma chave de API: o que cada plano inclui.