Throughput e limites de taxa da WhatsApp Cloud API explicados

Quais códigos de erro aparecem quando atinjo um limite?

Associe o código ao limite e depois escolha a resposta.

Os códigos 131048 e 131049 se relacionam com qualidade e engajamento, não com velocidade, então tentar mais rápido não ajuda. Veja solução de problemas dos códigos de erro da API do WhatsApp.

Na API da OmniChannels.ai, uma rejeição do upstream chega como HTTP 502, com o código de erro e o texto da Meta em message, e o nosso próprio limite de taxa retorna 429 com um cabeçalho Retry-After. Veja erros e limites para a tabela completa e os limites padrão.

Como devo enfileirar e repetir os envios?

Coloque uma fila entre a sua aplicação e a API, limite a taxa abaixo do seu teto e repita apenas o que pode dar certo depois.

1. Enfileire todos os envios. Sua aplicação grava as mensagens em uma fila e um pool de workers a esvazia. Nunca percorra uma lista de clientes em um único handler de requisição.
2. Limite a taxa com um token bucket abaixo do seu throughput, deixando margem para respostas e outros tráfegos que compartilham o mesmo teto.
3. Registre cada tentativa antes. Grave uma linha por mensagem com a sua própria chave de operação, guarde o ID de mensagem retornado e ignore o que já foi aceito.
4. Repita falhas transitórias. Limitações e erros temporários do servidor são repetidos; erros de validação (400), de autenticação e de template não são.
5. Use backoff com jitter. Espere mais a cada tentativa, adicione aleatoriedade para que os workers não repitam juntos e limite tanto o atraso quanto o número de tentativas.
6. Respeite o Retry-After quando a resposta o incluir.
7. Verifique antes de reenviar após um timeout. Uma resposta perdida não significa uma mensagem perdida; olhe antes os eventos de status.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function sendWithBackoff(send, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) throw new Error(`failed: ${res.status}`);
    const wait = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1)); // full jitter
    await new Promise((r) => setTimeout(r, wait));
  }
}

A página de throughput da Meta não traz uma regra de backoff para o erro 130429, então isto é prática padrão de engenharia. Para um 502 que traga um código de limitação da Meta, trate-o como repetível; para qualquer outro código do upstream, leia primeiro a mensagem. Nossa página de erros e limites tem a tabela completa de retries e a proteção contra envio duplicado.

Como planejo um envio grande?

Calcule o tempo, os limites e a carga de webhooks antes de começar.

1. Conte os destinatários únicos e compare com o seu limite de mensagens. Comece pelo plano de escala segura se a lista for maior que a sua faixa.
2. Estime a duração. As mensagens divididas pelo seu throughput dão os segundos. Em termos de aritmética, 100.000 mensagens a 80 por segundo levam 1.250 segundos, cerca de 21 minutos, se nada mais usar o teto.
3. Reserve capacidade. O teto também conta as mensagens recebidas, então deixe margem para as respostas dos clientes durante o envio.
4. Dimensione o seu servidor de webhook. A Meta diz que os servidores de webhook devem suportar três vezes o seu tráfego de mensagens enviadas mais o tráfego de entrada esperado, com latência mediana de no máximo 250 ms e menos de 1% das requisições acima de 1 segundo. Veja o guia de webhooks.
5. Verifique antes a saúde e a qualidade do template e divida o envio em lotes para poder parar se as falhas ou os bloqueios aumentarem. Veja envio em massa sem ser banido.
6. Use media IDs em vez de links ao enviar arquivos em volume, como a Meta aconselha. Veja tipos e limites de mídia.

Na OmniChannels.ai, os endpoints em massa aceitam muitos destinatários em uma única requisição, e um campo delay pode limitar o ritmo da entrega. Combine os picos com a nossa equipe com antecedência.

Exemplo prático: uma liquidação relâmpago em Dubai

A "Marina Gadgets" (sintética) planeja um template de liquidação relâmpago para 60.000 clientes com opt-in.

1. O limite deles permite, então o volume não é a restrição; a velocidade é. A 80 mps, 60.000 mensagens levam 750 segundos.
2. Eles enviam em seis lotes de 10.000, com um limitador de taxa a 60 mps, o que deixa margem para as respostas.
3. Um lote apresenta vários erros 131056 para clientes que também receberam uma atualização de pedido naquele minuto. Eles adiam esses envios por alguns minutos.
4. Um worker repete as requisições limitadas com backoff e jitter, e nenhuma mensagem é repetida depois de receber um ID.
5. O endpoint de webhook armazena os eventos e retorna 200; depois, um worker atualiza os status.
6. Após cada lote, eles verificam as falhas e a qualidade do template antes de continuar.

Quais são os erros mais comuns?

• Confundir os limites. Throughput, limite por par, Graph API e limite de mensagens são problemas diferentes.
• Repetir imediatamente, o que mantém o número no teto e prolonga o problema.
• Enviar no teto, de modo que as respostas e os status concorram com a campanha.
• Reenviar após um timeout sem verificar o status, o que duplica mensagens.
• Fazer polling em endpoints da Graph API em um laço e atingir o limite por hora.
• Servidores de webhook subdimensionados que ficam para trás e disparam retries.
• Os limites mudam. Este guia traz os valores da Meta no momento da redação.

Como a OmniChannels.ai ajuda

A BroadNet é uma Meta Business Solution Provider oficial, e a OmniChannels.ai envia WhatsApp por uma única API, com endpoints em massa, um campo delay para limitar o ritmo, agendamento e status de entrega em um formato de webhook normalizado. Os revendedores têm webhooks e créditos separados por subconta. Planeje os picos com a nossa equipe e leia a documentação da API do WhatsApp, os erros e limites e a página de campanhas.