Media download error
Failed to download the media from the sender.
Business eligibility — Payment issue
Message failed to send because there were one or more errors related to your payment method.
Check your payment setup in WhatsApp Manager and try again.
Message is not valid
Message failed to send because it was pending for too long (i.e., > 1 day).
This is expected if the WhatsApp Business API client is down for more than a day, then restarted.
Message failed to send during its Time To Live (TTL) duration.
Rate limit hit
Message failed to send because there was an error related to your certificate.
Certificate ID mismatch
Message failed to send because there was an error related to your certificate.
Certificate signature invalid
Occurs when a message is sent but the business client's certificate is not properly signed using the client's identity keys. This likely indicates that the client re-registered with new identity keys but did not go through the full certificate creation flow.
Message failed to send because more than 24 hours have passed since the customer last replied to this number.
Spam Rate limit hit
Message failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.
User's number is part of an experiment
Failed to send message because this user's phone number is part of an experiment.
User potentially changed
Message failed to send since the user with this phone number has potentially changed.
Message failed to send because of an unknown error.
Message too long
Message length exceeds 4096 characters.
Invalid recipient type
Valid recipient types:
Resource already exists
Possible UUID conflict for media upload request or media with that UUID already exists.
Resource not found
File or resource not found
Recipient blocked to receive message
Recipient is not on the allow list
Required parameter is missing
Missing a required parameter
Parameter value is not valid
Value entered for a parameter is of the wrong type or other problem.
Parameter is not required
Contains a parameter that is not required.
Service not ready
User is not valid
Too many requests
Client-side rate limit has been hit
If the system is under heavy load, this error is returned to allow the system to recover from the load.
Not Primary Master
This error occurs when a master-only request, such as set settings, get settings, import, export, code request, register, etc. is sent to a node that is not a primary master. This could happen when the WhatsApp Business API Client is not setup properly or internal errors.
Not Primary Coreapp
This error occurs when requests are sent to a Coreapp node that is not the shard owner or in the process to become the shard owner. You might see this error when we are doing shard failover in the multiconnect setup.
Retrying the request should resolve this error most of time. If not, contact Support.
This error occurs when you send a message to yourself.
Webhooks URL is not configured
This error occurs if you have not configured the REST API Webhooks format.
Database error occurred
Password Change Required
You are required to change your password.
The request is not valid.
The receiver is incapable of receiving this message.
You sent a message to a WhatsApp user who has potentially changed, and a
Template Param Count Mismatch
Number of parameters provided does not match the expected number of parameters.
Template does not exist for a language and locale.
Template Fetch Failed
The receiver failed to download the template.
Template Pack Missing
No templates exist for a specific language and locale.
Template Param Length Too Long
Parameter length too long
Template Hydrated Text Too Long
Translated text too long
Template White Space Policy Violated
Whitespace policy violated
Template Format Character Policy Violated
Format character policy violated
Template Media Format Unsupported
Media format used is unsupported
Template Required Component Missing
Required component in the Template is missing
Template Invalid Hydrated URL
URL in button component is invalid
Template Invalid Phone Number
Phone Number in button component is invalid
Template Parameter Format Mismatch
Parameter format does not match format in the created Template
Template Buttons Unsupported
Buttons are unsupported by the receiver
These are HTTP Status Codes that could be used by the WhatsApp Business API Client.
Successfully created (For POST requests)
Request was invalid
Method not allowed.
Message is rate limited
Too many requests
Internal server error
This is caused by a bug in an old version of the iOS client. We expect the errors to reduce overtime as the general population upgrades.
First check the callbacks for critical errors to diagnose the problem.
If you are seeing "Conflict: Detected multiple instances that share the same number", you need to check your containers. The most likely cause is you have multiple Docker containers trying to connect to the WhatsApp servers using the same WhatsApp account. Make sure you have only one container up and running. If you have old containers, shut them down and the error will go away.
If you want to test our more complicated high availability solution, see the High Availability documentation.
This is a known issue. Sometimes upgrading the WhatsApp Business API Client using the CloudFormation scripts also ends up requiring an update to the RDS DB stack. The new RDS stack won't have the same hostname as the original stack, and the Docker containers aren't able to connect to the database. The solution is to SSH into the EC2 instance created by CloudFormation and update the
whatsapp.conf file with the new host name, then restart the Docker containers so they pick up the new settings.
This error occurs when the database has not been set up correctly.
This happens if the Docker bridge is corrupted. The best remedy for this is to stop the Docker service and start it again. You can also try
docker restart on your containers.
A "connection refused" error likely means the Coreapp is not running. Use
docker ps to see if the Coreapp is up. If it is not up, take a look at the Docker logs. The Coreapp may be unable connect to the database. Make sure your database is set up correctly.
There are many reasons for this. Your Coreapp might be down or your database was not setup correctly. If these are not the case, please take a look at your Coreapp logs (or master Coreapp logs if you are running multiconnect). If you see database connection errors, it is likely your database is running out of connections. See the MySQL doc or PostgreSQL doc on this error.
We recommend bumping up the number of database connections on your database. 1000 database connections should be a safe number, but please make your own informed decision on number of connections. If the error persists, please open a support ticket.
If you are seeing this error but the missing mandatory parameter it refers to is set in your json body, it could be a json parsing error. This error can occur when the entire json payload is unparseable because of json formatting errors. Check the values of those parameters for invalid json characters, like a carriage return at the end. Sometimes parameters can be copied in with extra whitespace that might have characters that break json.
Structure unavailable errors occur when the phone cannot read the the template message.
Message templates are stored on the server, and when a templated message is sent using the
messages node, only the namespace, language, element name, and localized parameters are sent to the phone but not the entire message. Once these values are delivered to the phone, it tries to render the message.
If any errors occur during rendering, a
structure unavailable error is send to the callback URL containing the recipient and message ID. These errors can happen due to a wrong namespace, localized parameter mismatch, wrong element name, etc.
Go to the WhatsApp Manager in your Facebook Business Manager to view the correct number of parameters. Double check that the namespace is correct and that the element name exists.
One common source of errors is not creating translations for all templates in use. For example, if you have 2 templates you generally send and you add a new language translation for one template, please make sure to add that new language translation for another template also. If you are planning to support more than one language, you need to provide translations for all templates in all supported languages.
The good news is that the vast majority of time a
structure unavailable error is due to mistakes in the
messages API call and can be fixed by changing the send payload.
This error is due to Coreapp is not yet initialized. It means registration may not have gone through successfully. Please try registration before making a call to another end point. First step after installing WhatsApp Business API is login. Second step is registration. These two steps are necessary before making requests to any other end points.
All builds of the WhatsApp Business API Client have an expiry of 6 months from the date of release. If you see this error, upgrade to the latest released version as soon as possible.
WhatsApp runs experiments to measure and understand the impact of WhatsApp Business API notifications on user experience and the overall product in general. If the user you are messaging is in one of these experiments, they may not receive notifications from you even if they have opted in to receiving them.
If you are receiving an error similar to the following when setting up your AWS deployment, try changing to a stack name that uses 8 characters or less.
Country Name (2 letter code) [AU]:State or Province Name (full name) [Some-State]:Locality Name (eg, city) :Organization Name (eg, company) [Internet Widgits Pty Ltd]:Organizational Unit Name (eg, section) :Common Name (e.g. server FQDN or YOUR name) :string is too long, it needs to be less than 64 bytes long Common Name (e.g. server FQDN or YOUR name) :Email Address :error, no objects specified in config file problems making Certificate Request Created device key for internal-wa-inc-name-LB-123456789.ap-southeast-1.elb.amazonaws.com
The following are message template send side validation errors and why you may see them:
template. See the Media Message Templates documentation for more information.
For WhatsApp Business API client's running v2.21.6, when the client is disconnected from the server it may remain disconnected for a few minutes (up to 4 minutes) and then will retry the connection. Upgrading to v2.23.4 will allow for less downtime for a client when attempting to connect to the server.
v2.29.x, it was possible for the outgoing message queue size to grow over time due to a bug. Upgrading to
v2.29.3 resolves this issue.
The Coreapp will check the
/usr/local/waent/log directories within the Coreapp container, ensuring there is at least 10 MB of storage, otherwise it will give this critical error.
Check your logs and data directory to ensure you have enough space.