Troubleshooting Common Issues
Solutions for the most common API errors and how to resolve them quickly and effectively. Get your WhatsApp Business API back on track with these proven solutions.
Quick Solutions
- • Authentication and API token issues
- • Message delivery problems
- • Webhook configuration errors
- • Rate limiting and quota issues
- • Media upload and format problems
Authentication Issues
Error 401: Unauthorized
This error occurs when your API token is invalid, expired, or missing.
{
"error": {
"code": 401,
"message": "Unauthorized",
"details": "Invalid or expired API token"
}
}Check API Token
Verify your API token is correct and hasn't been regenerated
Regenerate Token
Generate a new API token in your dashboard if the current one is invalid
Check Authorization Header
Ensure the Authorization header format is correct: "Bearer YOUR_TOKEN"
Error 403: Forbidden
This error indicates your API token doesn't have the required permissions for the operation.
Check Token Permissions
Verify your API token has the necessary scopes for the operation
Regenerate with Correct Scopes
Create a new token with the required permissions
Message Delivery Issues
Error 131026: Message Undeliverable
The recipient's phone number is not a WhatsApp number or the number is invalid.
Verify Phone Number Format
Ensure the phone number includes country code (e.g., +1234567890)
Check WhatsApp Registration
Verify the recipient has WhatsApp installed and registered
Use WhatsApp Number Check API
Validate numbers before sending messages
Error 131021: Message Failed
The message failed to send due to various reasons like content policy violations or technical issues.
Check Message Content
Ensure message content complies with WhatsApp policies
Avoid Spam Keywords
Remove any spam-like content or promotional language
Check Message Format
Verify the message structure and required fields
Rate Limiting Issues
Error 429: Too Many Requests
You've exceeded the rate limit for API requests. This is a temporary restriction.
{
"error": {
"code": 429,
"message": "Too Many Requests",
"retry_after": 60
}
}Implement Exponential Backoff
Wait progressively longer between retries (1s, 2s, 4s, 8s, etc.)
Respect Retry-After Header
Wait for the time specified in the retry_after field
Implement Request Queuing
Queue messages and send them at a controlled rate
Rate Limit Best Practices
Message Limits
- • 80 messages per second
- • 10,000 messages per day (verified)
- • 1,000 messages per day (new accounts)
Implementation Tips
- • Monitor response headers
- • Implement request queuing
- • Use batch operations when possible
- • Start with lower volumes
Webhook Issues
Webhook Not Receiving Events
Your webhook endpoint is not receiving events from CMzon.
Check HTTPS Requirement
Ensure your webhook URL uses HTTPS, not HTTP
Verify SSL Certificate
Ensure your SSL certificate is valid and not expired
Check Firewall Settings
Ensure your server allows incoming connections from CMzon
Test Webhook Endpoint
Use tools like ngrok or webhook.site to test your endpoint
Webhook Signature Verification Failing
Your webhook signature verification is failing, causing requests to be rejected.
Check Webhook Secret
Ensure you're using the correct webhook secret from your dashboard
Use Raw Request Body
Make sure you're using the raw request body for signature verification
Check Algorithm
Ensure you're using HMAC-SHA256 for signature generation
Media Upload Issues
Error 400: File Too Large
The media file exceeds the size limit for the specific media type.
Check File Size Limits
Images: 5MB, Videos: 16MB, Documents: 100MB, Audio: 16MB
Compress Media Files
Use compression tools to reduce file size while maintaining quality
Use Alternative Formats
Convert to more efficient formats (JPEG for images, MP4 for videos)
Error 400: Unsupported Format
The media file format is not supported by WhatsApp Business API.
Supported Image Formats
- • JPG, JPEG
- • PNG
- • GIF (static only)
Supported Video Formats
- • MP4
- • 3GPP
- • MOV
Debugging Tools
API Testing Tools
- • Postman: Test API endpoints and debug requests
- • curl: Command-line testing and debugging
- • Insomnia: API client with debugging features
- • CMzon Dashboard: Built-in API testing tools
Webhook Testing
- • ngrok: Create secure tunnels for local testing
- • webhook.site: Test webhook endpoints
- • RequestBin: Capture and inspect webhook payloads
- • Local Development: Use localhost with tunneling
Still Having Issues?
Our support team is here to help you resolve any technical issues quickly and efficiently.