This article explains the most common WhatsApp errors that can occur when sending messages or connecting your WhatsApp Business API channel to bitbybit.
Messaging Errors
Messaging-related issues may prevent messages from being sent, delivered, or formatted properly. When this happens, bitbybit will return an error code to help you identify the cause.
An error code is a numeric or alphanumeric identifier that provides insight into what went wrong, whether it's a formatting issue, an invalid parameter, or a limitation with your account or setup. These codes help you troubleshoot faster by pointing to the likely cause and suggesting next steps.
Cloud API Error Reference
Below is a list of common WhatsApp Cloud API error codes, their possible causes and suggested solutions based on WhatsApp’s official documentation.
⚠️ For a complete list of error classifications refer to the full WhatsApp Cloud API Error Codes documentation.
| Code | Details | Possible reasons and solutions | HTTP Status Code |
|---|---|---|---|
| 1 | API Unknown | Invalid request or possible server error. Check the WhatsApp Business Platform Status page to see API status information. If no server outages, check endpoint reference and verify your request format and requirements. | 400 Bad Request |
| 2 | API Service | Temporary due to downtime or overload. Check status before retrying. | 503 Service Unavailable |
| 33 | Parameter value is not valid | The business phone number has been deleted. Verify the phone number. | 400 Bad Request |
| 100 | Invalid parameter | Unsupported or misspelled parameters. Validate parameters, key formats, length restrictions, and ID consistency. | 400 Bad Request |
| 130472 | User's number is part of an experiment | Message was not sent as part of an experiment. See Marketing Message Experiment. | 400 Bad Request |
| 131000 | Something went wrong | Unknown error during message send or signature calculation. Retry. Contact support if persistent. | 500 Internal Server Error |
| 131005 | Access denied | Your Facebook account access has been revoked or is incomplete. Please reconnect your Facebook account and ensure that all necessary permissions are granted during login. | 403 Forbidden |
| 131008 | Required parameter is missing | See endpoint reference to identify required parameters. | 400 Bad Request |
| 131009 | Parameter value is not valid | One or more values are invalid. Check endpoint reference and phone number requirements. | 400 Bad Request |
| 131016 | Service unavailable | Temporary service issue. Check status page before retrying. | 500 Internal Server Error |
| 131021 | Recipient cannot be sender | Sender and recipient phone numbers are the same. Use a different recipient. | 400 Bad Request |
| 131026 | Message Undeliverable | Check recipient number, TOS acceptance, client version, and confirm communication availability. | 400 Bad Request |
| 131037 | Display name approval needed | Change the phone number's display name and ensure it is approved. | 400 Bad Request |
| 131042 | Business eligibility payment issue | Verify billing settings. Common issues include: no payment account, over limit, deleted or suspended WABA, unset timezone/currency. | 400 Bad Request |
| 131045 | Incorrect certificate | Register the phone number before sending messages. | 500 Internal Server Error |
| 131047 | Re-engagement message | Use a message template if more than 24 hours since recipient’s last reply. | 400 Bad Request |
| 131049 | Meta chose not to deliver | Do not retry immediately if you do receive this error code and suspect it is due to the limit. Instead, retry in increasing larger time increments until the message is delivered, since the limit may be in effect for differing periods of time. See Per-User Marketing Template Message Limits for additional information. | 400 Bad Request |
| 131050 | User has stopped marketing messages | Do not retry. User opted out. Subscribe to user preferences webhook to track status. | 400 Bad Request |
| 131051 | Unsupported message type | Use a supported message type as per documentation. | 400 Bad Request |
| 131052 | Media download error | Could not download user media. Request user to send via other method. | 400 Bad Request |
| 131053 | Media upload error | Media upload failed. Check file format and MIME type. | 400 Bad Request |
| 131057 | Account in maintenance mode | Account is undergoing maintenance, e.g., throughput upgrade. | 500 Bad Request |
| 132000 | Template Param Count Mismatch | Mismatch in number of parameters. Ensure all required template values are included. | 400 Bad Request |
| 132001 | Template does not exist | Template not approved or not available in specified language. Check template status and name. | 404 Not Found |
| 132005 | Template Hydrated Text Too Long | Translated text too long. Verify translation and length limits. | 400 Bad Request |
| 132007 | Template Format Character Policy Violated | Template content violates policy. See rejection reasons. | 400 Bad Request |
| 132012 | Template Parameter Format Mismatch | Parameters formatted incorrectly. Follow template formatting rules. | 400 Bad Request |
| 132015 | Template is Paused | Template paused due to low quality. Edit and resubmit for approval. | 400 Bad Request |
| 132016 | Template is Disabled | Template permanently disabled due to repeated low quality. Create a new one. | 400 Bad Request |
| 132068 | Flow is blocked | Flow is in a blocked state. Fix the flow configuration. | 400 Bad Request |
| 132069 | Flow is throttled | Flow message limit exceeded. Wait before retrying. | 400 Bad Request |
| 133000 | Incomplete Deregistration | Deregister the number again before registering. | 500 Internal Server Error |
| 133004 | Server Temporarily Unavailable | Server down. Check status and retry after review. | 503 Service Unavailable |
| 133005 | Two step verification PIN Mismatch | Verify and resend correct PIN. To reset PIN: disable and resend with new PIN. | 400 Bad Request |
| 133006 | Phone number re-verification needed | Verify number before registering it. | 400 Bad Request |
| 133008 | Too Many two step verification PIN Guesses | Too many PIN attempts. Wait as per details response value. | 400 Bad Request |
| 133009 | Two step verification PIN Guessed Too Fast | Wait before retrying. See details response value. | 400 Bad Request |
| 133010 | Phone number Not Registered | Register the number before attempting message send. | 400 Bad Request |
| 133015 | Wait before registering | Phone number recently deleted. Wait 5 minutes before retrying. | 400 Bad Request |
| 135000 | Generic user error | Unknown request error. Check endpoint syntax. Contact support if it persists. | 400 Bad Request |