Limites de uso

Como ler a sua cota

A cota acompanha a sua chave, não o endereço de onde a requisição sai: distribuir o seu sistema por várias máquinas não multiplica o limite, e sair pelo mesmo endereço que outro integrador não o divide.

Toda resposta da REST traz o estado da cota:

Cabeçalho	Significa
RateLimit-Limit	Requisições permitidas na janela
RateLimit-Remaining	Quantas restam
RateLimit-Reset	Segundos até a janela reiniciar

Estourar devolve 429 com Retry-After em segundos. Espere esse tempo. Repetir antes não adianta e a tentativa ainda conta contra você.

Portador de chave tem tratamento próprio

	Sem chave	Com chave
Sustentado	1 req/s	10 req/s
Rajada	1	20
Fila de espera	5 requisições	nenhuma

A diferença que muda o seu código não é o teto, é a fila. Sem chave, a requisição excedente espera em vez de ser recusada. Com chave, o 429 vem na hora.

É deliberado: um cliente de servidor prefere uma recusa imediata, que ele sabe repetir depois do Retry-After, a uma requisição pendurada segurando conexão e estourando o tempo limite do lado dele.

Consequência prática: se os seus números parecem baixos demais, ou se as respostas demoram em vez de falhar, verifique antes de tudo se a credencial está mesmo chegando ao servidor. Uma chave que se perde num proxy não gera erro de autenticação nas rotas públicas: ela simplesmente rebaixa você ao limite do anônimo.

Não faça polling

O erro de dimensionamento mais comum é tratar a REST como canal ao vivo. Um cliente pedindo readings/latest de trinta estações a cada dez segundos são 259 mil requisições por dia, para receber os mesmos dados que uma única conexão WebSocket entrega de graça, e com menos atraso.

Você quer	Use
Dado ao vivo, poucas estações	WebSocket
Dado ao vivo, muitas estações	AMQP
Histórico	Rota de série, uma requisição por período

Reduzindo consumo

Cacheie o catálogo. GET /v1/stations muda raramente. Guarde o ETag e reenvie em If-None-Match: quando nada mudou a resposta é 304, sem corpo e sem custo de banda.

Peça série, não leitura bruta. Um mês de dados brutos de uma estação de 8 segundos são centenas de milhares de pontos e dezenas de requisições paginadas. O mesmo mês em resolution=1h cabe em uma resposta, e é o que um gráfico mensal consegue desenhar de qualquer forma.

Pagine até o fim, sem adivinhar. Siga o nextCursor enquanto ele vier. Pular páginas por conta própria ou repetir a primeira em laço são as duas formas mais rápidas de queimar cota sem obter dados.

Limites do WebSocket

Limite	Valor
Estações por conexão	50
Conexões simultâneas por chave	negociável
Tickets emitidos	contam contra a cota da REST

Reconexão em laço sem espera crescente queima cota de ticket rápido. Ver reconexão.

Limites do AMQP

Não há cota de mensagens: o relay empurra na cadência das estações. O que existe é limite de tamanho e tempo de vida da fila, e um consumidor fora do ar por tempo demais perde as mensagens mais antigas, descartadas para dar lugar às novas. Ver Relay AMQP.

Precisando de mais

Os tetos são negociáveis. Antes de pedir aumento, confira se o canal escolhido é o certo: quase todo pedido de cota maior na REST se resolve melhor migrando para WebSocket ou AMQP.