# Limites e ritmo

Fonte: https://lunahia.com.br/docs/limites-e-ritmo

A regra de todo limite da Luna cabe numa frase: ele existe por capacidade de infraestrutura e é igual para todos os clientes. Nenhum varia por preço. Esta página junta os que importam a quem envia muito, por exemplo um agente de IA, com o que cada um faz quando você passa dele.

A lista viva, com o valor e o motivo de cada limite, está em `GET /v1/limits` (escopo `numbers:read`). O contrato de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia).

## Os limites, numa tabela

| Limite | Valor | O que acontece quando você passa |
| --- | --- | --- |
| Requisições por chave | 600 por minuto | `429` com `error: "rate_limited"` e `Retry-After`. Espere o tempo indicado. Veja [Erros](https://lunahia.com.br/docs/erros#limite). |
| Rajada de cada conversa (o mesmo número de origem e o mesmo destinatário) | 30 mensagens de uma vez, depois uma a cada 7 segundos | Nada falha: a mensagem espera na fila e sai na ordem. O `202` volta igual, e esse limite nunca vira `429`. |
| Envios por número | 55 por segundo (20 por segundo num número em coexistência) | O que passa do ritmo espera na fila e sai na ordem. O valor vivo está em `GET /v1/limits`. |
| Fila de envio por número | 5.000 mensagens pendentes | `429` com `error: "queue_full"` e `Retry-After`, o tempo que a fila leva para escoar. Nada foi aceito: repita depois, com a mesma `Idempotency-Key`. |
| `/read` e `/typing` | Dividem o ritmo por segundo do número | `429` com `error: "number_rate_limited"` e `Retry-After`. São síncronas e perdem o valor com o tempo: se passar, espere e tente, ou deixe para a resposta. |
| Conversas novas por dia (da Meta) | A faixa de `limiteDiarioDeConversas` | A Meta recusa o envio e o motivo chega em `message.status` com `failed`. Veja a seção abaixo. |
| Operações de gestão da conta de negócio (criar e editar template, por exemplo) | 150 por hora numa conta sem número registrado, e 3.750 por hora com número | `429` com `error: "management_busy"` e `Retry-After`. O teto é compartilhado com a conexão do número, então um laço que cria muitos templates pode atrasar uma conexão. |
| Texto de uma mensagem | 4096 caracteres | `400` com `campos`. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#basico). |
| `typingMs` | De 1 a 25000 milissegundos | `400` com `campos`. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#lida-e-digitando). |
| Arquivo enviado à Luna | 100 MB | `413` com `error: "file_too_large"`, antes de qualquer chamada à Meta. |
| Endpoints de webhook por conta | 25 | `409` com `error: "webhook_endpoint_limit"`. Remover um libera a vaga. |
| Tempo que o seu endpoint tem para responder | 10 segundos | A entrega conta como falha e é retentada. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#entrega). |

> Por que a rajada é de 30 e uma a cada 7 segundos, e não os números da Meta? A Luna opera com folga sobre o que a Meta publica, porque a contagem dela não é visível de fora. Você não precisa se ajustar a isso: a Luna aceita, enfileira e entrega no ritmo certo.

## O que espera e o que falha

Há duas famílias de limite, e a diferença decide o seu código. Os de **ritmo** (a rajada de cada conversa e os envios por número) nunca falham: a mensagem é aceita com `202` e a Luna a entrega quando o ritmo permite, na ordem. Os de **recusa** (requisições por chave, fila cheia, `/read` e `/typing`) respondem `429` com `Retry-After`, e nada foi aceito.

- Num `429`, espere o `Retry-After` e repita **com a mesma `Idempotency-Key`**: se a primeira tentativa chegou, a repetição devolve a mensagem original em vez de enviar duas vezes.
- Um agente que responde em rajada não precisa de `sleep` entre as mensagens: a espera acontece na fila da Luna.
- A rajada vale **dentro de cada conversa**: uma conversa lenta não atrasa as outras do mesmo número.
- O estado de uma mensagem que espera é `queued`, e o `sent` chega quando ela sai. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#estados).
- O código de repetição pronto, em Node e Python, está em [Erros](https://lunahia.com.br/docs/erros#limite).

## O limite diário de conversas

Este é um limite **da Meta**, e a Luna só o mostra. `GET /v1/numbers` devolve, em cada número, `limiteDiarioDeConversas`: o nome da faixa em que a Meta colocou o portfólio empresarial (`TIER_250`, `TIER_2K`, `TIER_10K`, `TIER_100K` ou `TIER_UNLIMITED`; a Meta pode acrescentar outras). Ele conta pessoas únicas a quem o negócio **começa** conversa fora da janela de atendimento, num período de 24 horas, e não mensagens, e é o mesmo para todos os números do portfólio. Conversar com quem escreveu primeiro, dentro da [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela), não conta.

- O campo diz o teto que a Meta concedeu, e **nunca** quanto você já usou. Não há rota que devolva o consumo.
- **O limite inicial.** Um portfólio empresarial novo começa em `TIER_250`: 250 pessoas únicas a quem você começa conversa por período de 24 horas ([documentação da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)). Quem **escreveu primeiro** dentro da janela de atendimento não conta. Para subir, a Meta pede a verificação do negócio (ou do parceiro que o conectou), ou o envio de 2.000 mensagens entregues fora da janela, a pessoas únicas e com templates de boa qualidade, em 30 dias; depois disso a subida é automática (10 mil, 100 mil, sem limite) com qualidade alta e uso de metade do limite atual em 7 dias. Para um cliente novo, planeje o primeiro envio em massa abaixo de 250 pessoas por dia.
- Quando a Meta muda a faixa, o evento `account.limit_changed` avisa. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta).
- Passou do teto: a Meta recusa o envio e o motivo chega em `message.status` (`failed`), no campo `error`. Veja [Erros](https://lunahia.com.br/docs/erros#envio).
- Não confunda com `throughputLevel`, que é a **velocidade** (mensagens por segundo) e não a quantidade de conversas.

## O que nenhum limite é

Nenhum limite desta página é uma cota por plano. O plano da Luna define uma coisa só: quantos números a conta mantém ativos ([Plano e números](https://lunahia.com.br/docs/plano-e-numeros)). O teto de requisições, o ritmo e a fila são os mesmos para todos, e existem por capacidade.
