WhatsApp API Rate Limits Explained: How to Scale Without Getting Blocked

#whatsapp #api #backend #tutorial

Nothing kills a campaign faster than watching it fail mid-send. If you've hit a wall sending WhatsApp messages, you're probably running into one of three different mechanisms that all get lumped together as "rate limits" — and they need different fixes.

Three separate systems, one confusing name

Messaging limits (volume). Meta's cap on how many unique phone numbers you can contact first, outside an existing conversation, in a rolling 24-hour window. Replying to an inbound message doesn't count — every conversation gets a free 24-hour service window once the customer messages you first.

Throughput (speed). How fast you're sending, in messages per second. Push past it and you get error 130429 ("message throughput has been reached") — a backoff signal, not a ban.

Session-based API limits. If you're on a session-based API rather than the official platform, the messaging-tier system doesn't apply — you're bound by your plan's fixed rate limit and monthly request quota instead.

The official tier ladder

WhatsApp Business Accounts move up automatically based on usage quality and consistency — you can't buy your way up:

Tier	Unique contacts / 24h
Starting tier	250
Tier 2	2,000
Tier 3	10,000
Tier 4	100,000
Tier 5	Unlimited

Here's the part that trips people up: daily headroom doesn't protect you from throughput errors. A Tier 4 account with 100,000 contacts of daily allowance can still throttle if it tries to send 90,000 messages in one hour — that's a throughput problem, not a volume problem, and the two are tracked independently.

Session-based plan limits

Plan	Requests/mo	Sessions	Rate limit
Basic	100 (hard limit)	1	10 req/sec
Pro	1,000 + overage	3	10 req/sec
Ultra	10,000 + overage	10	20 req/sec
Mega	50,000 + overage	Unlimited	25 req/sec

What actually triggers a block vs. a throttle

Meta's error codes tell you which problem you have:

130429 — Throughput limit reached. You're sending too fast, slow down.
131056 — Recipient rate limit. Too many messages to one number too quickly.
131048 — Message quality throttling. Recent blocks/reports from recipients triggered a restriction.
80007 — Account rate limit. The whole WhatsApp Business Account hit capacity.

Underneath all of these is quality rating — built from block rates, spam reports, and engagement. A spike in blocks can drop you from Green to Red fast, and your access shrinks automatically with it. Sending too fast gets you throttled. Sending badly gets you blocked. They're different problems with different fixes.

Pacing your sends (code)

Whatever plan you're on, respect the per-second cap yourself instead of hoping the API queues for you:

// Respect per-second caps regardless of plan
async function sendBatch(numbers, message, session, requestsPerSecond = 10) {
  const delayMs = Math.ceil(1000 / requestsPerSecond);

  for (const [i, chatId] of numbers.entries()) {
    await axios.post(
      'https://whatsapp-messaging-bot.p.rapidapi.com/v1/sendText',
      { chatId, text: message, session },
      {
        headers: {
          'x-rapidapi-key': process.env.RAPIDAPI_KEY,
          'x-rapidapi-host': 'whatsapp-messaging-bot.p.rapidapi.com',
        },
      }
    );
    console.log(`Sent ${i + 1}/${numbers.length}`);
    await new Promise((r) => setTimeout(r, delayMs));
  }
}

How to actually scale safely

Warm new numbers. Low, steady volume for 1–2 weeks before pushing real traffic through them.
Segment your lists. Opted-in, recently engaged contacts only for marketing sends — this is what protects your quality rating.
Back off on 429s. Exponential backoff, not a retry loop.
Watch delivery and block/report rates as leading indicators, not just your send success rate.
Route support replies through the 24-hour window. Customer-initiated conversations bypass daily messaging limits entirely — the safest volume you can send is a reply.

Practical patterns

E-commerce: queue order confirmations instead of firing them all at once — customers still get them in seconds, you stay under the cap.
SaaS OTPs: provision headroom above your average signup rate for predictable spikes (Monday mornings, post-outage recovery).
Support teams: lean on inbound-triggered replies — they mostly sidestep rate limits altogether.

Key takeaways

"Rate limit" is really two things — daily volume caps and independent per-second throughput.
Tier upgrades on the official platform are earned through consistent, quality usage, not purchased.
Session-based APIs skip the tier ladder for a flat plan-level limit.
Quality rating (driven by recipient behavior) determines your real access more than raw volume does.
Support replies inside the 24-hour window are the safest sends you can make.

Full API reference: https://whatsapp-messaging.retentionstack.agency/docs/api-reference

Originally published on Retention Stack.

DEV Community