Limites e ritmo

Todo teto que um App encontra, num lugar só. Os de App são próprios e menores que os humanos: um bot mal escrito não fecha a porta de quem usa o produto.

O 429, e por que ele quase nunca chega até você

Todo teto responde 429 com RATE_LIMIT_EXCEEDED, o cabeçalho Retry-After em segundos e, no corpo, retryAfterSeconds (e resetAt quando o instante da liberação é conhecido). A decisão é sempre a mesma — esperar —, e o SDK já espera: com ruído para cima, para cem processos não voltarem no mesmo milissegundo.

Onde	O teto da espera	O que acontece acima dele
`REST`	`maxRetryDelayMs`, 30 s por padrão	O SDK devolve o erro com `retryAfterSeconds` e sai da frente. Dormir dez minutos dentro de uma chamada que quem escreveu acha rápida é pior do que a recusa.
`Gateway`	5 minutos, teto de sanidade	A espera pedida acima disso é truncada: aqui não há chamada de ninguém esperando, e desistir da conexão seria pior do que dormir.

Retry-After é o número do servidor, e voltar antes dele bate na porta fechada e gasta mais uma tentativa. As opções que mudam esses tempos estão em Instalar e configurar.

O gateway

Teto	Valor	O que ele protege
`conexões por App`	2	Concorrência, e não taxa: o que libera vaga é outra conexão cair, então a recusa não promete instante de liberação. As duas vagas são suas.
`conexões no total`	50	O teto do gateway inteiro, dividido com todo mundo. É o único número desta lista que não depende só de você.
`aberturas por minuto`	10	Abrir e fechar em laço custa uma consulta de instalações por vez, mesmo com uma só conexão viva. É freio diferente do de cima: um é quantas coexistem, o outro é quantas você começa.
`leituras da caixa`	90 por minuto	O recuo em JSON tem balde próprio, e não consome vaga de conexão. Perguntar em laço apertado responde `429`.
`prazo da caixa`	45 segundos sem leitura	Depois disso ela é varrida, e a resposta é `409` com `MAILBOX_EXPIRED`.
`eventos na caixa`	400 entre duas leituras	Passar disso não poda o mais antigo: a caixa esvazia inteira e a leitura seguinte responde o mesmo `409`. Entregar os mais novos e calar sobre o buraco daria um vão silencioso no meio da conversa.
`janela de retomada`	500 eventos ou 120 segundos	O que vier primeiro. Fora dela a resposta honesta é `connection_open`, que significa recomece.

O batimento de 25 segundos não é teto: ele existe para dar o que ler a quem está esperando, e quem detecta o silêncio é o SDK. O ciclo inteiro está em Gateway.

O REST, por família

Cada família de rota tem balde próprio, e a chave é app:<application id>:<família> — por App, e não por servidor. É a informação que muda o desenho de quem está em vinte casas: o teto protege o Trivo do volume de uma máquina, e um App instalado em vinte servidores é uma máquina só.

Família	Teto	O que ela cobre
`mensagens`	5 a cada 10 s	Escrever no canal — o método sendMessage. É o teto mais apertado da plataforma.
`leitura`	60 a cada 60 s	Ler: o retrato do servidor, a lista de membros, a página de mensagens.
`apagar-mensagens`	15 a cada 60 s	Apagar mensagem — a própria ou, com a permissão, a de outra pessoa.
`reacoes`	15 a cada 60 s	Reagir e desreagir. Mais barato que escrever, e não de graça: cada toggle grava, conta o agregado e publica evento para o canal inteiro.
`administrar`	15 a cada 60 s	Canal, categoria, cargo e atribuição — toda a administração num balde só.
`interacoes`	120 a cada 60 s	As três rotas de resposta. Folgado de propósito: uma interação só consome de uma a sete chamadas, e um 429 que chega depois de a interação expirar é a pior recusa possível.

O registro de comando tem o balde comandos, na seção abaixo; a leitura da caixa e a abertura de conexão têm os deles, na seção do gateway. Os tetos de App nascem menores que os humanos de propósito: um bot mal escrito faz em um minuto o que uma pessoa faz num dia, e soltar a corda depois é fácil — apertar depois de terceiros terem escrito código em cima do teto largo é que não é.

Comandos

Teto	Valor
`registros por minuto`	30, por App
`opções por nível`	25
`escolhas por opção`	25 — acima disso o caminho é `autocomplete`
`grupos de subcomando`	Um nível, garantido pelo tipo
`a árvore inteira`	Um teto em nós, em que escolha, argumento e subcomando contam igual

Estourar um teto de quantidade de comandos responde COMMAND_LIMIT_EXCEEDED, que serve aos do App (globais ou por servidor) e aos visíveis num servidor. O resto está em Comandos.

Interações

Prazo	Valor	Por quê
`confirmar`	3 segundos	É onde "lento" vira "quebrado" para quem clicou. Cabe uma volta pela rede e o seu handler; não cabe uma consulta pesada — que é o que a resposta diferida existe para acomodar.
`autocompletar`	1 segundo	Ele dispara por tecla, e sugestão que chega depois de mais três letras pisca e some. Não há passo de confirmação porque não há nada a confirmar.
`resposta diferida`	60 segundos depois do defer	O marcador "pensando" é interface parada.
`seguimentos`	5, em 10 minutos	O teto existe porque o seguimento alcança a resposta privada: sem ele, o token viraria canal de mensagem direta por fora do funil.
`desligamento do endpoint`	20 falhas seguidas, em pelo menos 15 minutos	Falha é qualquer coisa que não seja 2xx no prazo, timeout incluído. Um sucesso no meio zera o contador.

Passar do teto de seguimentos responde FOLLOWUP_LIMIT_EXCEEDED; passar do prazo, INTERACTION_EXPIRED. Os dois estão em Erros.

Conteúdo

Teto	Valor
`content de mensagem`	4000 caracteres. A validação da rota é mais frouxa que a do serviço, então um texto entre 4001 e 5000 passa no parse e volta como `INVALID_INPUT`: valide em 4000.
`página de mensagens`	50, fixa. Sem `limit` e sem cursor: para subir o histórico, mande em `antesDe` o `publicId` da mensagem mais antiga que você já tem.
`lista de membros`	500 pessoas, sem paginação, com `truncated` avisando que passou.

Os tetos de componente — blocos por mensagem, itens por linha, opções por seleção e o teto em bytes do conjunto — saem do próprio vocabulário e estão em Componentes e formulários.