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.
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. |
| 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. |
typingMs | De 1 a 25000 milissegundos | 400 com campos. Veja Enviar mensagens. |
| 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. |
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 oRetry-Aftere repita com a mesmaIdempotency-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
sleepentre 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 osentchega quando ela sai. Veja Enviar mensagens. - O código de repetição pronto, em Node e Python, está em Erros.
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, 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). 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_changedavisa. Veja Saúde da conta. - Passou do teto: a Meta recusa o envio e o motivo chega em
message.status(failed), no campoerror. Veja Erros. - 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). O teto de requisições, o ritmo e a fila são os mesmos para todos, e existem por capacidade.