WhatsApp Cloud API Throughput and Rate Limits Explained

Which error codes appear when I hit a limit?

Match the code to the limit, then choose the response.

Codes 131048 and 131049 relate to quality and engagement rather than speed, so retrying faster will not help. See WhatsApp API error codes troubleshooting.

On the OmniChannels.ai API, an upstream rejection arrives as HTTP 502 with Meta's error code and text in message, and our own rate limiting returns 429 with a Retry-After header. See errors and limits for the full table and the default limits.

How should I queue and retry?

Put a queue between your application and the API, limit the rate below your cap, and retry only what can succeed later.

1. Queue every send. Your application writes messages to a queue and a worker pool drains it. Never loop over a customer list in one request handler.
2. Limit the rate with a token bucket set below your throughput, leaving room for replies and other traffic that share the same cap.
3. Record each attempt first. Write a row per message keyed by your own operation ID, store the returned message ID, and skip anything already accepted.
4. Retry transient failures. Throttling and temporary server errors are retried; validation errors (400), authentication errors and template errors are not.
5. Back off with jitter. Wait longer after each attempt, add randomness so workers do not retry together, and cap both the delay and the number of attempts.
6. Honour Retry-After when the response includes it.
7. Check before resending after a timeout. A lost response does not mean a lost message; look at status events first.

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));
  }
}

Meta's throughput page gives no backoff rule for error 130429, so this is standard engineering practice. For a 502 that carries a Meta throttling code, treat it as retryable; for any other upstream code, read the message first. Our errors and limits page has the full retry table and duplicate-send protection.

How do I plan a large send?

Work out the time, the limits and the webhook load before you start.

1. Count unique recipients and compare with your messaging limit. Start with the safe scaling plan if the list is bigger than your tier.
2. Estimate duration. Messages divided by your throughput gives seconds. As arithmetic, 100,000 messages at 80 per second take 1,250 seconds, about 21 minutes, if nothing else uses the cap.
3. Reserve capacity. The cap also counts inbound messages, so leave headroom for customer replies during the send.
4. Size your webhook server. Meta says webhook servers should handle three times your outgoing message traffic plus your expected incoming traffic, with a median latency not above 250 ms and under 1% of requests above 1 second. See the webhooks guide.
5. Check template health and quality first, and stage the send in batches so you can stop if failures or blocks rise. See bulk messaging without getting banned.
6. Use media IDs rather than links when sending files at volume, as Meta advises. See media types and limits.

On OmniChannels.ai, bulk endpoints take many recipients in one request and a delay field can throttle delivery. Agree peak plans with our team in advance.

Worked example: a flash sale in Dubai

"Marina Gadgets" (synthetic) plans a flash-sale template to 60,000 opted-in customers.

1. Their limit allows it, so volume is not the constraint; speed is. At 80 mps, 60,000 messages need 750 seconds.
2. They send in six batches of 10,000 with a rate limiter at 60 mps, which leaves room for replies.
3. A batch shows several 131056 errors for customers who also got an order update that minute. They delay those sends by a few minutes.
4. A worker retries throttled requests with jittered backoff, and no message is retried after it has an ID.
5. The webhook endpoint stores events and returns 200, then a worker updates statuses.
6. After each batch they check failures and template quality before continuing.

What are the common mistakes?

• Confusing limits. Throughput, pair, Graph API and messaging limits are different problems.
• Retrying immediately, which keeps the number at the cap and extends the problem.
• Sending at the cap, so replies and statuses compete with the campaign.
• Resending after a timeout without checking status, which duplicates messages.
• Polling Graph API endpoints in a loop and hitting the hourly limit.
• Undersized webhook servers that fall behind and trigger retries.
• Limits change. This guide gives Meta's values at the time of writing.

How OmniChannels.ai helps

BroadNet is an official Meta Business Solution Provider, and OmniChannels.ai sends WhatsApp through one API with bulk endpoints, a delay field for throttling, scheduling and delivery statuses in one normalised webhook format. Resellers get separate webhooks and credit per sub-account. Plan peaks with our team, and read the WhatsApp API docs, errors and limits and the campaigns page.