Messaging Errors & Delivery Failures

Even when you use the correct API call, WhatsApp may still block message delivery.
Delivery failures commonly stem from one of the following areas:

This guide explains the most frequent causes and how to diagnose and resolve them.

1. Quick Reference: Most Common Failure Causes

Cause	Applies to	Impact
Expired Token	All message types	API call fails immediately
Tier Limit Reached	Templates & Free-form	Messages blocked until limit resets
Closed 24h Window	Free-form messages only	Must use template instead
Template Policy Violation	Template messages	Template rejected or paused
Invalid Phone Number	All messages	No delivery possible

2. Error Summary Table

Category	Issue	Typical Error Codes	Description	How to Fix
Rate Limits	Messaging Tier Limit Reached		Daily recipient limit exceeded.	Improve quality rating, upgrade tier, reduce volume.
	API Rate Limit Exceeded	`429`	Too many requests sent in a short time.	Implement retry/backoff, throttle requests.
Account / Config	Invalid or Expired Access Token	`OAuthException`	Token is missing, invalid or expired.	Refresh token, ensure correct scopes.
	Wrong `phone_number_id` / Unlinked Number		Number not connected to your WABA.	Verify number in Business Manager and API config.
	Business Not Verified		Lower limits, blocked sends.	Complete Business Verification.
Policy Violations	Template Misuse		Content does not match approved template purpose.	Use template only as approved; adjust text.
	User Marked Messages as Spam		Poor quality rating leads to restrictions.	Improve messaging relevance and opt-in quality.
	Recipient Rejects Message		User blocked or opted out.	Stop messaging this contact.
Phone Number Issues	Number Invalid or Not on WhatsApp		Number does not exist or is not on WhatsApp.	Validate number format and WhatsApp registration.

Recommended References
For deeper technical details, consult: