Failed to download the media from the sender.
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 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.
Message failed to send because there was an error related to your certificate.
Message failed to send because there was an error related to your certificate.
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.
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.
Failed to send a message because this user's phone number is part of an experiment.
Message failed to send since the user with this phone number has potentially changed.
Message failed to send because of an unknown error.
Message length exceeds 4096 characters.
Valid recipient types:
Possible UUID conflict for media upload request or media with that UUID already exists.
File or resource not found
Recipient is not on the allow list
Missing a required parameter.
Value entered for a parameter is of the wrong type or other problem.
If you’re trying to send a List Message, check if each row’s ID is unique.
Contains a parameter that is not required.
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.
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.
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 the time. If not, contact Support.
This error occurs when you send a message to yourself.
This error occurs if you have not configured the REST API Webhooks format.
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
Number of parameters provided does not match the expected number of parameters.
Template does not exist for a language and locale.
The receiver failed to download the template.
No templates exist for a specific language and locale.
Parameter length too long
Translated text too long
Whitespace policy violated
Format character policy violated
Media format used is unsupported
Required component in the Template is missing
URL in button component is invalid
Phone Number in button component is invalid
Parameter format does not match format in the created Template
Buttons are unsupported by the receiver
Message request contains below minimum or above the maximum number of sections. See
You need to have at least 1
There is an invalid number of rows. For List Messages, there must be at least one
Format character policy has been violated.
Returned when the
Message Template Limit Exceeded
You have exceeded the maximum number of message templates you can have for this WhatsApp business account.
This phone number is eligible to be added directly, and does not need to use phone migration APIs.
Add the phone number to your WhatsApp account from Business Manager directly, and proceed with registration.
The source WABA must be approved, and its "messaging on behalf of" must be approved.
Work with the business that owns the source WABA to set up the account correctly or to deactivate it, and then retry migration.
The destination WABA must be approved before you can migrate phone numbers.
Ensure business verification is completed, and WABA’s account review status is approved.
The destination WABA’s "Messaging For" request must be approved by the client.
Ask your client to accept your "Messaging For" request.
Migrate your phone number into a WABA that is messaging for the same business as the source WABA.
The phone number you are trying to migrate is already present in your WhatsApp account.
Try again with a phone number that is not already present in your WhatsApp account.
Something went wrong when trying to migrate your phone number.
Try again after some time. If that doesn’t work, contact support.
Certificate can be downloaded only after confirming ownership of a phone number that is being migrated.
In order to download the certificate and proceed with registration, request for a registration code and verify it.
Phone ownership verification APIs are not available for this use case.
Verify and register the number using Enterprise Client
Two-factor authentication must be disabled for this phone number.
Ask your client to reach out to the source WABA to disable two-factor authentication before trying to migrate.
Your WhatsApp account must have an active credit line in order to send messages after migration.
Follow steps here to set up a credit line for your WhatsApp account, or share your credit line using Business Manager or API.
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.