> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictor.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Limites

> Os tetos, o orçamento por rota, e por que o de vídeo é diferente.

## Teto geral

Há um teto de requisições **por chave, por minuto**. Ao estourar, a resposta é
`429` com `Retry-After` em segundos — espere o que ele diz antes de tentar de
novo.

O teto é **por chave**, não por IP: rodar sua integração 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.

## Teto de vídeo

A emissão de URL de mídia (`/api/devices/{id}/media-url`) tem um teto próprio, bem
menor que o geral.

O motivo é o custo, e vale entender: cada emissão acorda uma sessão de vídeo no
servidor de mídia. Isso não é uma linha de JSON — é CPU, e a capacidade é contada
em sessões simultâneas por servidor. Um laço de retry nessa rota não degradaria a
API: **apagaria o vídeo da conta inteira**.

<Tip>
  Peça a URL **quando for exibir**, não em lote e não de forma preventiva. A URL tem
  prazo próprio; guardá-la para depois não economiza chamada, só entrega um endereço
  que já venceu.
</Tip>

## O orçamento, por rota

Não existe push: quem pergunta é o seu lado ([por quê](/introducao)). Então o
orçamento importa, e ele se planeja antes de escrever o laço.

| Rota                                | Cadência recomendada                                | Por quê                                                 |
| ----------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
| `GET /api/devices`                  | 1×/hora para cadastro, 1×/min para o eixo de imagem | o inventário muda em dias; o eixo de imagem, em minutos |
| `GET /api/analytics/events`         | 1×/min                                              | cobre operação; abaixo disso é vigília                  |
| `GET /api/patrols/sheets`           | 1×/10 min                                           | ronda roda em cadência de minutos                       |
| `GET /api/recording-segments`       | sob demanda                                         | ninguém revê gravação em laço                           |
| `GET /api/devices/{id}/diagnostics` | **sob demanda**                                     | disca na câmera de verdade                              |
| `GET /api/devices/{id}/media-url`   | **no clique**                                       | acorda sessão de vídeo                                  |
| `GET /api/video-walls`              | 1×/hora                                             | mural muda quando alguém o edita                        |

### A conta que decide o seu desenho

O erro caro é varrer diagnóstico. Compare, para uma operação de **40 condomínios
com 25 câmeras cada**:

| Desenho                                      | Requisições por volta | O que acontece                                            |
| -------------------------------------------- | --------------------- | --------------------------------------------------------- |
| diagnóstico por câmera                       | **1.000**             | estoura o teto, e cada uma abre uma sessão no equipamento |
| `GET /api/devices?transmitting=no` por conta | **1 por conta**       | mesma resposta, e o custo é uma consulta                  |

<Warning>
  **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.
</Warning>

Precisa do estado de muitas câmeras sem tocar em nenhuma? `probe=false` devolve só
o que já se sabe, sem nenhuma chamada de rede.

## Boas práticas de polling

* **Inventário**: uma vez por hora cobre qualquer operação real.
* **Eixo de imagem** (`?transmitting=no`): uma vez por minuto, pela conta inteira.
  Confira `transmitting_witness_fresh` antes de concluir — em `false`, "nenhuma sem
  imagem" significa "não deu para medir".
* **Diagnóstico**: sob demanda, quando alguém for olhar.
* **Eventos**: avance com `since` a partir do último que você já tem, em vez de
  reler o mesmo período. Se uma janela devolveu exatamente `limit` linhas, ela
  transbordou — caminhe para trás com `until`. Ver
  [Ler os eventos sem varrer](/receitas/ler-os-eventos-sem-varrer).
* **Retry**: respeite o `Retry-After` do `429`. Em `5xx`, espere com recuo
  progressivo. Nunca faça 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.

<Warning>
  **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 de verdade.
</Warning>

Baixe no mesmo momento em que decide guardar. Para reabrir depois, peça o recurso
de novo: a assinatura sai nova.