Limites de velocidade

As cotas de mensagens e contatos por ciclo de faturamento estão em Cota e uso, junto com os erros 402/429 de cota. Esta página documenta apenas os limites de velocidade, um conceito separado.

Cotas e limites de velocidade

Cota e limite de velocidade são controles diferentes:

	Cota	Limite de velocidade
O que mede	Volume total consumido no ciclo de faturamento (mensagens, contatos distintos)	Velocidade instantânea de envios e chamadas
Janela	Ciclo de faturamento avaliado (cycle_start → cycle_end)	Segundos ou minutos, sem relação com o ciclo
Reseta em	resets_at (fim do ciclo)	Poucos segundos depois (Retry-After)
Erros típicos	402 contact_quota_exceeded · 429 messages_quota_exceeded	429 send_rate_spacing · 429 rate_limit_exceeded
Documentado em	Cota e uso	Esta página

Velocidade de envio (por plano)

Cada mensagem enviada via API respeita um intervalo mínimo em relação ao envio anterior no mesmo número: é o espaçamento entre envios que ajuda a proteger o número no WhatsApp. O intervalo depende do plano:

Plano	Intervalo mínimo entre envios	Equivalente em mensagens/min
Gratuito	6s	10 msg/min
Lobo Solitário	1.2s	50 msg/min
Empresarial	0.6s	100 msg/min
Personalizado	0.4s	150 msg/min

Enviar antes do intervalo mínimo desde o último envio bem-sucedido naquele número retorna 429 com o código send_rate_spacing e o cabeçalho Retry-After (em segundos: o tempo restante até o próximo envio permitido):

Status HTTP: 429

• Retry-After: 2

{
  "error": "send_rate_spacing"
}

Este limite é por número (principal ou extra): cada número tem seu próprio relógio de espaçamento, então usar números extras aumenta a capacidade total de envio da conta.

Atualização de contatos (por plano)

O endpoint de atualização de contato (POST .../contacts/{contact_id}/refresh) consulta o WhatsApp na hora, ao contrário de uma leitura simples, e por isso tem o seu próprio limite por minuto, que também cresce com o plano:

Plano	Atualizações/min
Gratuito	5
Lobo Solitário	30
Empresarial	120
Personalizado	600

Estourar esse limite retorna 429 refresh_rate_limited com o cabeçalho Retry-After.

Pareamento de números extras

Cada POST /v1/numbers/{ref}/pair pede ao WhatsApp um código novo, que gera uma notificação no celular do número, ou um QR code novo. O limite protege o número de ser bloqueado pelo próprio WhatsApp por excesso de pedidos:

Escopo	Pedidos/min
Por número	10
Por conta	30

Estourar qualquer um retorna 429 pairing_rate_limited com o cabeçalho Retry-After. Veja Pareamento pela API.

Proteção contra rajadas (igual em todos os planos)

Estes limites são fixos e valem para todos os planos:

• messages_per_minute: 10.000 envios/minuto por número (proteção contra rajadas). Cada número tem a sua própria contagem, somando todas as requisições enviadas por ele.
• recipients_per_day: 2.000 mensagens/dia para o mesmo destinatário, por número (proteção contra bloqueio). Não há limite de destinatários distintos por dia: você pode alcançar quantos contatos quiser, respeitando as demais cotas do plano.

Controles internos

Além dos limites de velocidade, o Turbo Notify aplica controles internos para proteger a infraestrutura e evitar abusos. Esses controles podem restringir temporariamente o envio em situações como:

• Picos anormais de tráfego vindos de uma única conta.
• Padrões de envio que possam comprometer a estabilidade do serviço.
• Alta taxa de falhas ou rejeições consecutivas.

Regras do WhatsApp

O WhatsApp tem regras e limites próprios, que valem além dos limites do Turbo Notify. Mensagens que os destinatários não pediram, ou que denunciam como spam, podem levar o WhatsApp a restringir o número mesmo dentro desses limites.

As recomendações de Proteja o seu número ajudam a evitar isso, junto com as políticas do WhatsApp (abre em nova aba) .

Erros relacionados

Status	Código de erro	Descrição
429	send_rate_spacing	Envio antes do intervalo mínimo entre mensagens do plano, no mesmo número.
429	refresh_rate_limited	Limite de atualizações de contato ultrapassado.
429	messages_per_minute_limit_exceeded	Proteção contra rajadas: mais de 10.000 envios/minuto no mesmo número (veja acima).
429	recipients_per_day_limit_exceeded	Proteção contra bloqueio: 2.000 mensagens/dia para o mesmo destinatário, por número (veja acima).
429	warmup_limit_exceeded	Número conectado há poucos dias: o volume diário é liberado aos poucos para o WhatsApp não tratar o número novo como suspeito. O cabeçalho Retry-After indica quantos segundos faltam para o limite diário renovar (meia-noite UTC).
429	duplicate_burst_blocked	O mesmo texto foi enviado para mais de 20 destinatários na última hora, pelo mesmo número. Varie o conteúdo ou espace os envios.
429	reply_ratio_too_low	Poucas respostas recebidas em relação ao que o número enviou, sinal de envio não solicitado. Reduza o volume para quem não interage. Vem sem Retry-After: esperar não resolve, o envio volta a ser aceito quando os contatos respondem ou o volume cai.
429	pairing_rate_limited	Pedidos de pareamento (código ou QR code) acima do limite, veja Pareamento de números extras.
429	rate_limit_exceeded	Limite geral de requisições à API da sua organização ultrapassado (1.000 requisições por segundo). Requisições em paralelo são aceitas enquanto o total do segundo fica abaixo disso. Aguarde o Retry-After e tente novamente.
503	service_unavailable	Serviço temporariamente indisponível, inclusive quando não foi possível identificar o plano da organização. A requisição não foi processada. Tente novamente após alguns instantes.

Para os erros de cota (402 contact_quota_exceeded, 429 messages_quota_exceeded, 402 feature_not_available), veja Cota e uso.

Boas práticas

• Respeite o cabeçalho Retry-After ao receber um status 429.
• Distribua o envio ao longo do tempo em vez de enviar tudo de uma vez: o espaçamento mínimo do seu plano já define o ritmo sustentável.
• Utilize números extras para aumentar a capacidade de envio.
• Monitore os códigos de resposta da API para identificar rapidamente quando um limite é atingido.
• Configure webhooks para acompanhar o status das mensagens sem precisar consultar a API repetidamente.