WhatsApp error 4 (too many API calls): your Meta app hit its call limit, not your phone number

WhatsApp error 4 means your Meta app has made too many API calls. Meta's WhatsApp error reference titles it "Application Rate Limit" (HTTP 429 Too Many Requests) and says: "The app has reached its API call rate limit." The suggested solution is to "load the app in the App Dashboard and view the Application Rate Limit section to verify that the app has reached its rate limit. If it has, try again later or reduce the frequency or amount of API queries the app is making." The key word is app: this limit is not on your phone number, your messaging tier or one client's account.

Three rate limits that are easy to mix up

Meta groups all three as throttling errors. They need different fixes, so check the code before you change anything. Sending to the same customer too often is a fourth limit, the pair rate limit (131056), which works per recipient.

What the error looks like

Illustrative response (wording varies):

{
  "error": {
    "message": "(#4) Application request limit reached",
    "type": "OAuthException",
    "is_transient": true,
    "code": 4,
    "fbtrace_id": "AmX5tQ1pWc8NvR3kLb7yHzF"
  }
}

And the header to watch on every successful response before the error appears (values are percentages of your allowance; illustrative):

X-App-Usage: {"call_count":92,"total_time":41,"total_cputime":38}

When any of the three numbers nears 100, the next calls start failing with code 4. Meta's Graph API rate-limiting documentation describes these fields.

Why apps hit it

• Polling instead of webhooks. A job that asks for message status, template status or phone quality every few seconds. Meta sends these as webhooks; polling duplicates them.
• Retries without back-off. A failed call retried instantly in a loop multiplies the load at the worst moment.
• One app, many accounts. An agency's own app that manages 50 client accounts multiplies every scheduled job by 50.
• Batch jobs at the same minute. Every client's nightly sync starting at 00:00.
• Debug code left on. A dashboard page that refreshes all data each time a user opens it.

Step-by-step fix

1. Stop the bleeding. Pause scheduled jobs that call Meta, so sends that matter can get through.
2. Open the App Dashboard and look at the Application Rate Limit section, as Meta suggests. It shows whether the app is over its limit and when usage peaked.
3. Log X-App-Usage from every response for a day. Group calls by endpoint; the top one or two endpoints are usually most of the usage.
4. Replace polling with webhooks for message statuses, template status changes and account updates.
5. Cache what changes rarely. Phone number details, business profile and template lists can be cached for minutes or hours.
6. Retry with exponential back-off and jitter. Wait about 1 second, then 2, then 4, plus a random part, and give up after a few tries. A request rejected with code 4 was not processed, so retrying a send will not duplicate it.
7. Spread scheduled jobs across the hour instead of starting them together.

A worked example

Arjun runs a small agency in Pune with its own Meta app connected to 40 client WhatsApp Business accounts. His reporting dashboard calls Meta for each client's phone number quality, template list and analytics every 30 seconds while anyone has it open. On the Monday after Diwali, the whole team opens the dashboard, usage climbs, and client order confirmations sent by the same app start failing with error 4 (illustrative scenario).

He switches the dashboard to read from his own database, filled by webhooks and a template sync every 15 minutes per client, staggered across the quarter hour. Peak call_count drops to a fraction of what it was, and sends are never starved again. His rule now: user-facing screens never call Meta directly.

Preventing error 4

• Webhooks first. Treat any repeated GET to Meta as a design question.
• Throttle by priority. When usage is high, postpone background jobs and keep capacity for message sends.
• Respect Meta's wait hints such as Retry-After when present.
• Alert at 75 to 80 percent of X-App-Usage, not at the first failure.

How Broadchat handles app rate limits

Every call Broadchat makes to Meta goes through one Graph client that reads the X-App-Usage and X-Business-Use-Case-Usage headers and keeps a usage snapshot per app and per account. At 85 percent usage it postpones background work such as template sync and health refreshes; at 95 percent it also slows other calls slightly. It honours Meta's wait hints, and it treats code 4 as a rate-limit rejection: the request was not processed, so it is retried with exponential back-off and jitter, a few times at most. Status updates reach Broadchat by webhook rather than by polling. Your own integrations that call Meta with your own app have their own limit and need the same habits.

See the WhatsApp API error codes cheat-sheet for every code, or start with what the WhatsApp Business API is. Agencies serving many clients can read about the white-label platform.