Error and Status Messages

This document provides more information about the following types of error and status messages:

WhatsApp Business API Client Error Codes

Error CodeTitleDescription

400

Media download error

Failed to download the media from the sender.

402

Business eligibility — Payment issue

Message failed to send because there were one or more errors related to your payment method.

  • Payment account is not attached to a WhatsApp Account
  • Credit line is over the limit
  • Credit line (Payment account) not set or active
  • WhatsApp Business Account is deleted
  • Account has been suspended by us
  • Timezone not set
  • Currency not set
  • MessagingFor request (On Behalf Of (OBO)) is pending or declined

Check your payment setup in WhatsApp Manager and try again.

408

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.
Resend the message.

410

Message expired

Message failed to send during its Time To Live (TTL) duration.

429

Rate limit hit

  • For outgoing messages: Message failed to send because there were too many messages sent from this phone number in a short period of time.
    Resend the failed messages.

  • For incoming messages: Failed to download media successfully due to rate-limiting.
    Ask sender to resend the message.

430

Unsigned certificate

Message failed to send because there was an error related to your certificate.
Download a new certificate from the WhatsApp Manager and re-register.

432

Certificate ID mismatch

Message failed to send because there was an error related to your certificate.
Download a new certificate from the WhatsApp Manager and re-register.

433

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.

470

Re-engagement message

Message failed to send because more than 24 hours have passed since the customer last replied to this number.
Use a message template to respond.

471

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.
Check your quality status in the WhatsApp Manager. See the Quality-Based Rate Limits documentation for more information.

472

User's number is part of an experiment

Failed to send message because this user's phone number is part of an experiment.
Skip sending messages to this user.

480

User potentially changed

Message failed to send since the user with this phone number has potentially changed.

500

Generic error

Message failed to send because of an unknown error.
Try again later.

1000

Generic error

1001

Message too long

Message length exceeds 4096 characters.

1002

Invalid recipient type

Valid recipient types:

  • individual

1004

Resource already exists

Possible UUID conflict for media upload request or media with that UUID already exists.

1005

Access denied

  • Media directory is not writable (upload request), or
  • Invalid credentials, or
  • Certificate Error, or
  • App Expired: a version upgrade is required, or
  • Number is already registered on WhatsApp
    See Migrating a Phone Number for information on moving a phone number from WhatsApp to the WhatsApp Business API.

1006

Resource not found

File or resource not found

1007 (Deprecated)

Recipient blocked to receive message

Recipient is not on the allow list

1008

Required parameter is missing

Missing a required parameter

1009

Parameter value is not valid

Value entered for a parameter is of the wrong type or other problem.

1010

Parameter is not required

Contains a parameter that is not required.

1011

Service not ready

1013

User is not valid

1014

Internal error

  • Upload failed on bad image (image not uploaded correctly) or endpoint not found
  • Hash you provided does not match user’s latest hash

1015

Too many requests

Client-side rate limit has been hit

1016

System overloaded

If the system is under heavy load, this error is returned to allow the system to recover from the load.

1017

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.
Retrying the request should resolve this error. If this does not resolve the error, contact support.

1018

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.

1021

Bad User

This error occurs when you send a message to yourself.
To resolve, send the message to number that is not your own.

1022

Webhooks URL is not configured

This error occurs if you have not configured the REST API Webhooks format.

1023

Database error occurred

1024

Password Change Required

You are required to change your password.

1025

Invalid Request

The request is not valid.

1026

Receiver Incapable

The receiver is incapable of receiving this message.

1028

A user_identity_changed system notification requires acknowledgement

You sent a message to a WhatsApp user who has potentially changed, and a user_identity_changed system notification was sent to you and is pending acknowledgement.

2000

Template Param Count Mismatch

Number of parameters provided does not match the expected number of parameters.

2001

Template Missing

Template does not exist for a language and locale.

2002

Template Fetch Failed

The receiver failed to download the template.

2003

Template Pack Missing

No templates exist for a specific language and locale.

2004

Template Param Length Too Long

Parameter length too long

2005

Template Hydrated Text Too Long

Translated text too long

2006

Template White Space Policy Violated

Whitespace policy violated

2007

Template Format Character Policy Violated

Format character policy violated

2008

Template Media Format Unsupported

Media format used is unsupported

2009

Template Required Component Missing

Required component in the Template is missing

2010

Template Invalid Hydrated URL

URL in button component is invalid

2011

Template Invalid Phone Number

Phone Number in button component is invalid

2012

Template Parameter Format Mismatch

Parameter format does not match format in the created Template

2013

Template Buttons Unsupported

Buttons are unsupported by the receiver

HTTP Status Codes

These are HTTP Status Codes that could be used by the WhatsApp Business API Client.

HTTP CodeDescription

2xx

Success

200

Success (OK)

201

Successfully created (For POST requests)

302

Found

4xx

Client Errors

400

Request was invalid

401

Unauthorized

403

Forbidden

404

Not found

405

Method not allowed.

412

Precondition failed

420

Message is rate limited

429

Too many requests

5xx

Server Errors

500

Internal server error

504

Timeout

FAQ

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.

  • Make sure you are using either MySQL 5.7 or later or PostgreSQL 9.5.x, 9.6.x, 10.x.
  • Your database password should not contain any of these characters: ?{}&~!()^.
  • If you are using AWS, make sure your stack has a short name. See the Installation documentation for more information.

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.

You need to first check if the contact exists before sending a message. See the Contacts documentation for more information on how to do this.

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

An empty profile object will be returned if the the Business Profile is only partially populated. Please upgrade to v2.21.4 to resolve this issue.

See the Business Profile Settings documentation for more information about completing your business profile.

Error code 471 relates to quality-based rate limits. See the Quality-Based Rate Limits documentation for more information.

The following are message template send side validation errors and why you may see them:

  • "No message templates exist in language your-language" or "No message templates exist in language your-language and locale your-locale" — The given language pack does not exist. Check your Business Manager account.
  • "Template your-template-name does not exist in language your-language" or "Template your-template-name does not exist in language your-language and locale your-locale" — You are trying to use a template that does not exist (has not been created or is not yet approved). If you attempt to send a message with a template that was deleted, you will also get this error.
  • "Number of localizable_params num1 does not match the expected number of params num2" — You are trying to send a message template with parameters that do not match the number of parameters expected. Please check your API invocation for correctness.
  • "your-template-name is a rich template and requires the template message API to be used" — You are trying to send a media message template as a regular message template. Make sure the message type is template. See the Media Message Templates documentation for more information.
  • Once templates are approved in Business Manager (or deleted), it can take up to 20 minutes for the WhatsApp Business API client to receive the updated templates. If you are trying to send a message with a template that just got approved, and you get an error saying the template does not exist, you can retry sending the message after waiting the above specified time.

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.

Prior to 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/data and /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.