Throughput e rate limit na API do WhatsApp: mensagens por segundo e erro 131056

Atualizado em 28/10/2026

A Cloud API do WhatsApp aceita, por padrão, até 80 mensagens por segundo (mps) por número registrado, somando entrada e saída, e pode subir automaticamente para até 1.000 mps em números elegíveis. Quando você passa desse ritmo, a API devolve o erro 130429. Já o erro 131056 é outra coisa: é o pair rate limit, disparado quando você manda mensagens demais do mesmo número para o mesmo destinatário em pouco tempo.

Neste artigo você vê a diferença entre throughput, pair rate limit, limites de chamadas da API e limite de mensagens por 24 horas, quais códigos de erro cada um gera e um exemplo de fila com backoff em Node.js e Python.

Quatro limites que costumam ser confundidos

Quem integra a API pela primeira vez costuma chamar tudo de “rate limit”. Na documentação da Meta são limites diferentes, com causas e soluções diferentes:

Limite	O que mede	Erro	O que fazer
Throughput	Mensagens por segundo de um número	130429	Reduzir o ritmo e tentar de novo
Pair rate limit	Mensagens do seu número para o mesmo usuário em pouco tempo	131056	Esperar antes de enviar de novo àquele usuário
Limite de chamadas	Requisições do app ou da conta à API	4 (app) e 80007 (conta do WhatsApp Business)	Diminuir a frequência de chamadas
Limite de mensagens	Destinatários únicos fora da janela de atendimento em 24 horas, por portfólio	Envios recusados acima do limite	Subir de nível com qualidade e volume

O último não é sobre velocidade, e sim sobre alcance diário. Ele é explicado em detalhe em limite de mensagens da API do WhatsApp. Aqui o foco são os três primeiros.

Throughput: quantas mensagens por segundo

Pela página de throughput da Meta:

• Cada número registrado na Cloud API suporta até 80 mps por padrão.
• O throughput conta mensagens de entrada e de saída, de todos os tipos. Um número que recebe muitas mensagens tem menos folga para enviar.
• Números do app WhatsApp Business conectados à API (coexistência) têm throughput fixo de 20 mps.
• Acima do limite, a API responde com 130429 até o ritmo voltar ao permitido.

Upgrade automático para 1.000 mps

O número sobe sozinho para até 1.000 mps, sem custo e sem mudança de preço, quando cumpre as três condições:

1. O portfólio empresarial tem limite de mensagens ilimitado.
2. O número enviou mensagens para 100 mil ou mais números únicos de usuários fora da janela de atendimento em um período móvel de 24 horas.
3. O quality_score do número é amarelo (qualidade média) ou melhor.

Durante o upgrade, que pode levar até 1 minuto, o número fica indisponível e a API devolve o erro 131057. Ao terminar, chega um webhook phone_number_quality_update com event igual a THROUGHPUT_UPGRADE. Para conferir o nível atual de um número:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=throughput" \
  -H "Authorization: Bearer $TOKEN"

A mesma página traz duas recomendações práticas para quem envia em alto volume. Primeiro, seu servidor de webhook precisa aguentar cerca de 3 vezes o tráfego de saída (cada mensagem gera status de enviado, entregue e lido) mais 1 vez o tráfego de entrada, com latência mediana abaixo de 250 ms e menos de 1% das requisições acima de 1 segundo. Segundo, para mensagens com mídia, use IDs de mídia enviados antes por upload em vez de links para arquivos no seu servidor, para aproveitar o throughput maior.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Pair rate limit e o erro 131056

O throughput é pensado para campanhas que falam com muitos usuários diferentes. Se você mandar muitas mensagens para o mesmo usuário, esbarra em outro limite. A tabela de códigos de erro da Meta descreve o 131056 assim: mensagens demais enviadas do número remetente para o mesmo número destinatário em um curto período. A solução indicada é esperar e tentar de novo, se você realmente pretende enviar mais mensagens àquele número.

A Meta não publica nessa documentação um número exato para o pair rate limit, então não programe contra um valor fixo. Os cenários típicos que disparam o 131056:

• Um bot que quebra uma resposta longa em dez mensagens seguidas.
• Uma integração em loop que reenvia a mesma notificação várias vezes.
• Testes de carga apontados para um único número de teste.
• Um disparo com a lista duplicada, mandando o mesmo template duas vezes para cada contato.

A correção quase sempre é de desenho, não de infraestrutura: junte o conteúdo numa mensagem só, deduplique a lista e espace os envios para o mesmo contato. Para testes de carga, distribua os envios entre vários destinatários de teste.

Erros de chamada: 4, 80007 e 131048

Além dos limites de mensagem, a API também limita chamadas:

• 4: o app atingiu o limite de chamadas. A Meta indica conferir a seção de rate limit do app no painel e reduzir a frequência ou a quantidade de consultas.
• 80007: a conta do WhatsApp Business atingiu o limite de chamadas. Mesma solução: tentar depois e reduzir a frequência.
• 131048: não é de velocidade. Indica restrição de envio no número por causa de qualidade; a orientação é conferir o status de qualidade no WhatsApp Manager. Insistir com retry só piora. Veja qualidade do número na API.

Os erros de consulta (4 e 80007) aparecem com frequência em integrações que fazem polling, como consultar o status de templates ou de números a cada poucos segundos. Prefira os webhooks, que avisam quando algo muda.

Fila com backoff: o desenho recomendado

Para respeitar todos esses limites ao mesmo tempo, o desenho mais simples é uma fila com três regras:

1. Ritmo global por número: um limitador que libera no máximo N envios por segundo, com N abaixo do throughput do número (por exemplo, 60 para um número padrão de 80 mps, deixando folga para as mensagens recebidas).
2. Retry com backoff exponencial e jitter para 130429, 4 e 80007: espera 1 s, 2 s, 4 s, 8 s… com um pouco de aleatoriedade, até um teto.
3. Adiamento por destinatário para 131056: o envio volta para a fila daquele contato com atraso, sem travar a fila dos outros.

Erros que não são temporários, como 131048, não devem ser repetidos. Pare, registre e investigue.

Exemplo em Node.js

const GRAPH = 'https://graph.facebook.com/v26.0';
const RETRY_GLOBAL = new Set([130429, 4, 80007]);
const MPS = 60; // abaixo dos 80 mps padrão

const esperar = (ms) => new Promise((r) => setTimeout(r, ms));

async function enviar(phoneNumberId, token, payload) {
  const res = await fetch(`${GRAPH}/${phoneNumberId}/messages`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
  const json = await res.json();
  if (res.ok) return { ok: true, id: json.messages?.[0]?.id };
  return { ok: false, code: json.error?.code };
}

export async function processarFila(fila, phoneNumberId, token) {
  const intervalo = 1000 / MPS;
  while (fila.length) {
    const item = fila.shift();
    if (item.naoAntesDe && item.naoAntesDe > Date.now()) {
      fila.push(item); // ainda não é a vez deste contato
      await esperar(intervalo);
      continue;
    }

    const r = await enviar(phoneNumberId, token, item.payload);
    if (r.ok) {
      item.onSucesso?.(r.id);
    } else if (RETRY_GLOBAL.has(r.code) && (item.tentativas ?? 0) < 6) {
      item.tentativas = (item.tentativas || 0) + 1;
      const espera = Math.min(2 ** item.tentativas * 1000, 60000) + Math.random() * 500;
      await esperar(espera); // segura o número inteiro
      fila.unshift(item);
    } else if (r.code === 131056) {
      item.naoAntesDe = Date.now() + 30000; // adia só este destinatário
      fila.push(item);
    } else {
      item.onFalha?.(r.code); // 131048 e outros: não repetir
    }
    await esperar(intervalo);
  }
}

O atraso de 30 segundos para o 131056 é um ponto de partida, não um número da Meta: ajuste observando seus próprios logs. Em produção, troque o array por uma fila persistente (Redis, SQS, RabbitMQ) para não perder envios se o processo cair.

Exemplo em Python

import asyncio
import random

import httpx

GRAPH = "https://graph.facebook.com/v26.0"
RETRY_GLOBAL = {130429, 4, 80007}
MPS = 60


async def enviar(client, phone_number_id, payload, tentativas=0):
    r = await client.post(f"{GRAPH}/{phone_number_id}/messages", json=payload)
    if r.status_code == 200:
        return r.json()["messages"][0]["id"]

    code = r.json().get("error", {}).get("code")
    if code in RETRY_GLOBAL and tentativas < 6:
        await asyncio.sleep(min(2 ** tentativas, 60) + random.random() / 2)
        return await enviar(client, phone_number_id, payload, tentativas + 1)
    if code == 131056:
        await asyncio.sleep(30)  # adia só este destinatário
        return await enviar(client, phone_number_id, payload, tentativas + 1)
    raise RuntimeError(f"falha definitiva: {code}")


async def disparar(phone_number_id, token, payloads):
    headers = {"Authorization": f"Bearer {token}"}
    async with httpx.AsyncClient(headers=headers, timeout=30) as client:
        tarefas = []
        for p in payloads:
            tarefas.append(asyncio.create_task(enviar(client, phone_number_id, p)))
            await asyncio.sleep(1 / MPS)  # ritmo global
        return await asyncio.gather(*tarefas, return_exceptions=True)

Lembre que a resposta 200 só diz que a mensagem foi aceita. Falhas posteriores chegam no webhook de status com status: "failed" e o código em errors; trate os mesmos códigos nos dois lugares. O artigo status de mensagem via webhook mostra o formato.

Checklist antes de um envio grande

• Saiba o throughput do número (?fields=throughput) e configure o limitador abaixo dele.
• Se o número usa coexistência, conte com 20 mps.
• Deduplique a lista para não mandar a mesma mensagem duas vezes ao mesmo contato.
• Confira se o volume cabe no seu limite de mensagens de 24 horas.
• Dimensione o webhook para cerca de 3 vezes o tráfego de saída.
• Faça upload das mídias antes e envie por ID.
• Registre os códigos de erro para ajustar o ritmo com dados reais.

Para o planejamento da campanha como um todo, veja disparo em massa pela API oficial.

Como fazer isso com a Vectalk

A Vectalk é um proxy da Cloud API oficial da Meta, então os limites deste artigo são os da própria Meta: 80 mps por número no padrão, 20 mps em coexistência e os mesmos códigos de erro, que chegam no corpo da resposta e nos webhooks no formato da documentação oficial. O envio usa POST https://apis.vectalk.com.br/api/messages e o nível de throughput do número aparece no retorno de GET /phone-numbers da API da Vectalk. A lógica de fila e backoff mostrada aqui vale sem mudanças. Crie sua conta em apps.vectalk.com.br/register ou veja o guia rápido.

Se você ainda está montando a base da integração, veja também como validar a assinatura do webhook e como registrar o número na Cloud API. O panorama geral está no guia da API oficial do WhatsApp.

Perguntas frequentes

Quantas mensagens por segundo a API do WhatsApp envia?

Até 80 por segundo por número registrado, por padrão, contando entrada e saída. Números elegíveis sobem automaticamente para até 1.000 mps. Números em coexistência com o app WhatsApp Business ficam em 20 mps.

Qual a diferença entre o erro 130429 e o 131056?

O 130429 é de throughput: o número passou do ritmo total permitido, para qualquer destinatário. O 131056 é de pair rate limit: mensagens demais para o mesmo destinatário em pouco tempo. O primeiro pede reduzir o ritmo global; o segundo, espaçar envios para aquele contato.

Ter vários números aumenta a velocidade?

O throughput é por número, então vários números somam velocidade. Mas o limite de destinatários únicos em 24 horas é do portfólio e é compartilhado por todos os números, e a qualidade de cada um continua sendo avaliada. Mais números não resolvem limite de alcance.

Mensagem recusada por rate limit é cobrada?

A Meta cobra mensagens entregues. Uma mensagem recusada por 130429 ou 131056 não chega ao destinatário e não deveria ser cobrada; confira sempre os status no webhook para conciliar.

Como sei se meu número já tem 1.000 mps?

Consulte GET /PHONE_NUMBER_ID?fields=throughput. Quando o upgrade acontece, a Meta também envia o webhook phone_number_quality_update com o evento THROUGHPUT_UPGRADE.

---

Fontes oficiais consultadas em 28/10/2026: Throughput (Meta), Códigos de erro da Cloud API (Meta), Limites de mensagens (Meta), Números de telefone na API da Vectalk.