TL;DR: WhatsApp error 4 is a throttling error meaning your Meta app has exceeded its Graph API call rate limit — the total number of API calls the app makes, not message throughput. Meta's
detailsstring is "The app has reached its API call rate limit." Fix it with exponential backoff, caching, and reducing call frequency; the limit resets on a rolling window.
What Error 4 Means
Error 4 is an application-level rate limit on the Graph API. It counts all API calls your app makes (template fetches, phone-number/WABA management calls, status checks, etc.) — distinct from message throughput (130429) and from WABA-level (80007) and per-pair (131056) limits. Meta's official details value is:
"The app has reached its API call rate limit."
Per Meta's "About the WhatsApp Business Platform" documentation, the default budget is 200 requests per hour, per app, per WABA, and 5,000 requests per hour for active WABAs with at least one registered phone number.
Where You See It
Synchronous Graph API response (400 Bad Request). The current usage is visible in the App Dashboard → Application Rate Limit section. It is not a per-message status webhook event.
Common Causes
- Polling endpoints (template lists, phone-number status, WABA state) too frequently instead of using webhooks.
- Bursty management operations during a campaign (e.g. creating/fetching many templates at once).
- Not caching responses that rarely change, so the same endpoint is hit repeatedly.
- Many parallel workers all calling the Graph API without a shared rate budget.
How to Fix It
- Open App Dashboard → your app → Application Rate Limit and confirm the app is at its limit.
- Implement exponential backoff with jitter: on a 4, wait ~1s and double each retry.
- Cache responses for slow-changing data (templates, phone numbers) instead of refetching.
- Batch and space out non-urgent calls; avoid bursts.
- Where you have multiple numbers, distribute load; wait for the rolling window to reset, then retry.
How to Prevent It
- Replace polling with webhooks for template, phone-number, and account status updates.
- Keep a local cache/store of template definitions and refresh only on change events.
- Add a shared client-side rate limiter so concurrent workers respect one budget.
Related Errors
- WhatsApp Error 130429 — Cloud API message throughput reached.
- WhatsApp Error 80007 — WABA-level rate limit.
- WhatsApp Error 131056 — per-recipient pair rate limit.
- WhatsApp Webhook Override (Error 100)
- See the full error reference
FAQ
Q: Is error 4 the same as 130429? A: No. Error 4 is app-level API call frequency; 130429 is message throughput (messages per second).
Q: What are the actual limits? A: Per Meta, 200 requests/hour per app per WABA by default, and 5,000 requests/hour for active WABAs with at least one registered phone number.
Q: Can I raise the app rate limit? A: Graph app rate limits generally can't be manually increased — reduce/optimize call frequency instead.
Q: Does error 4 stop message sending? A: It blocks API calls while over the limit, which can interrupt sends and management operations until the window resets.
How Dualhook Helps
This is a platform/throttling code where Dualhook helps meaningfully. Because Dualhook holds advanced whatsapp_business_management access and pushes account/template/phone-number state via webhooks, it reduces your need to poll Meta — the single biggest driver of error 4. Use Webhook Events & Notifications and Messaging Health Status so status changes arrive as events instead of forcing repeated Graph calls from your app. Dualhook also documents backoff/retry strategy in the Meta API Error Reference. The retry/backoff logic in your own caller is still yours to implement.