Teto geral
Cada chave tem 600 requisições por minuto. Ao estourar, a resposta é 429
com Retry-After em segundos.
O teto é por chave, não por IP: rodar de vários servidores não multiplica o
limite. E não existe requisição de graça, uma resposta vazia custa o mesmo que
uma cheia.
Os cabeçalhos RateLimit-* da resposta não são o teto da sua chave. Eles vêm
da borda e contam um orçamento compartilhado por endereço de origem — dois
sistemas atrás do mesmo IP dividem esse número, e ele não sabe nada da sua
chave. Para saber quando voltar, use o Retry-After do 429, que é o único que
fala da sua chave.
Teto de vídeo
A emissão de URL de mídia (/api/devices/{id}/media-url) tem teto próprio de
12 por minuto por chave, bem menor que o geral. A diferença existe porque
esta chamada não é uma leitura: para devolver um endereço que abre, a plataforma
prepara a transmissão da câmera, e isso é um recurso caro.
Doze por minuto é o orçamento de quem pede no clique. Um mural de seis tiles
cabe duas vezes por minuto; pedir para as quarenta câmeras do condomínio de uma
vez não cabe nenhuma.
Se o 429 chegar, espere o Retry-After. Não faça retry imediato: a chamada
seguinte custa o mesmo que a primeira e não chega mais perto de abrir o vídeo.
Peça a URL quando for exibir. Ela tem prazo próprio, então guardar para
depois não economiza chamada, só entrega um endereço vencido.
O orçamento, por rota
A conta que decide o seu desenho
O erro caro é varrer diagnóstico. Para 40 condomínios com 25 câmeras cada:
Diagnóstico é sob demanda, não vigília. Com probe=true (o padrão) ele disca
na câmera. O desenho certo tem dois níveis: a frota diz quem está sem imagem;
o diagnóstico diz por quê, e só para as que apareceram.
Polling
- Inventário: com
updated_since o delta é barato — 1×/min cabe. A leitura
COMPLETA (sem updated_since) é a da primeira carga: 1×/hora basta.
- Eixo de imagem (
?transmitting=no): 1×/min, pela conta inteira. Confira
transmitting_witness_fresh antes de concluir. Em false, “nenhuma sem
imagem” significa “sem medição”.
- Diagnóstico: sob demanda, quando alguém for olhar.
- Eventos: avance com
since a partir do último que você já tem. Se uma
janela devolveu exatamente limit linhas, ela transbordou: caminhe para trás
com until. Ver Ler os eventos sem varrer.
- Retry: respeite o
Retry-After do 429. Em 5xx, recuo progressivo.
Nunca retry imediato em rota de mídia.
Prazos das URLs assinadas
Todo endereço de vídeo, foto ou gravação que a API devolve é assinado e vence.
Quem arquiva, arquiva os bytes. Guardar o link produz um dossiê que abre hoje
e falha em seis meses, e você descobre no dia em que alguém precisa dele.
