API Reference v1.0

Rate Limits & Best Practices

Understand the rate limits that apply to your WhatsBizAPI account and learn best practices for reliable, high-throughput messaging.

API Rate Limits

Rate limits vary by operation type and your account tier. These limits ensure platform stability and fair usage across all accounts.

Operation	Limit	Notes
Send Messages	80 messages/sec (default)	Up to 1,000 messages/sec for high-tier accounts with approved throughput increases.
Media Upload	25 requests/sec per phone number	Applies to image, video, audio, and document uploads.
Template Creation	Standard limits	Subject to Meta's template submission rate limits.
API Calls (general)	Based on plan	Check your dashboard under Settings → API for your current plan limits.

ℹ

Need higher throughput? If your use case requires sending more than 80 messages per second, contact our support team to request a throughput increase. High-tier accounts can reach up to 1,000 messages/sec.

Messaging Tiers

WhatsApp uses a tiered system that controls how many unique recipients you can message within a rolling 24-hour window. Your tier increases automatically as you demonstrate consistent, high-quality messaging.

Tier	Unique Recipients / 24 Hours	Requirement
Unverified	250	Default for all new accounts before business verification.
Tier 1	1,000	Complete business verification through Meta Business Manager.
Tier 2	10,000	Use 50% or more of your Tier 1 limit within a 7-day period.
Tier 3	100,000	Use 50% or more of your Tier 2 limit within a 7-day period.
Unlimited	No cap	Use 50% or more of your Tier 3 limit within a 7-day period.

⚠

Quality rating affects your tier. If your quality rating drops to Low (red), WhatsApp may downgrade your messaging tier or even restrict your account. Monitor your quality rating regularly in the Meta Business Manager dashboard and keep it at High (green) to maintain and upgrade your tier.

How Tier Upgrades Work

Tier upgrades happen automatically when you meet the usage threshold. Here is how the progression works:

Verify your business in Meta Business Manager to move from Unverified (250) to Tier 1 (1,000).
Send messages to 500+ unique recipients (50% of 1,000) within 7 days while maintaining a High or Medium quality rating to reach Tier 2.
Send messages to 5,000+ unique recipients (50% of 10,000) within 7 days to reach Tier 3.
Send messages to 50,000+ unique recipients (50% of 100,000) within 7 days to reach Unlimited.

⚠

Tier downgrades are possible. If your quality rating drops to Low, WhatsApp can reduce your tier limit. In severe cases, your account may be flagged or restricted entirely. Always prioritize message quality over volume.

Best Practices

Follow these guidelines to maximize deliverability, maintain a healthy quality rating, and avoid hitting rate limits.

Handling Rate Limits

Implement exponential backoff for 429 responses. Start with a 1-second delay, then double the wait time on each subsequent retry (1s, 2s, 4s, 8s, up to a maximum of 60s).
Spread campaign messages over time instead of sending them all at once. Use a message queue to throttle delivery at a sustainable rate.
Monitor your API usage in the WhatsBizAPI dashboard to stay within your plan limits and avoid unexpected throttling.

Exponential Backoff Example (JavaScript)

async function sendWithRetry(payload, maxRetries = 5) {
  let delay = 1000; // Start with 1 second

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('/api/wpbox/sendmessage', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });

    if (response.status !== 429) return response.json();

    console.log(`Rate limited. Retrying in ${delay}ms...`);
    await new Promise(resolve => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 60000); // Double delay, max 60s
  }

  throw new Error('Max retries exceeded');
}

Maintaining Quality Rating

Monitor your quality rating in the Meta Business Manager dashboard. Aim to keep it at GREEN (High) for tier upgrades and uninterrupted service.
Keep template quality high by ensuring your message content is relevant, expected, and valuable to recipients.
Honour opt-outs immediately. When a recipient indicates they no longer want to receive messages, remove them from your sending lists right away.
Segment your audience and send targeted, relevant messages rather than broadcasting the same content to everyone.

Delivery Optimization

Use webhooks to track delivery and read status instead of polling the API. Webhooks provide real-time updates and consume no API quota.
Validate phone numbers before sending. Ensure numbers include the correct country code and are formatted without spaces or dashes.
Batch your API requests where possible, but stay within the messages-per-second limit for your account tier.
Handle errors gracefully. Parse error codes from failed messages and implement appropriate retry or fallback logic for each error type.

✓

Pro tip: Set up a message queue (such as Redis or a database-backed queue) to manage outbound messages. This allows you to control throughput, retry failures automatically, and maintain a consistent sending rate even during high-volume campaigns.

Rate Limit Response Format

When you exceed a rate limit, the API returns an error response with details about the limit that was hit.

Rate Limit Error Response 429

{
  "status": "error",
  "error": {
    "code": 130429,
    "title": "Rate limit hit",
    "message": "Message throughput has been exceeded. Please reduce your sending rate and retry."
  }
}

ℹ

Related: For a complete list of error codes and their meanings, see the Error Codes Reference.