Error and Status Messages

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

For Embedded Signup troubleshooting, see Embedded Signup Flow Errors.

WhatsApp Business API Client Error Codes

Error CodeDescription

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
  • Exceeded conversation free tier threshold without a valid payment method. (This error type goes live on February 1, 2022).

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 the 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 a 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
  • button messages are disabled for this account, 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 - Recipient blocked to receive message (Deprecated)

Recipient is not on the allow list

1008 - Required parameter is missing

Missing a required parameter.


If you’re trying to send a List Message, it’s possible that you missed the title part of the section object or IDs for your rows.


If you’re trying to send a Single Product Message or a Multi-Product Message, it’s possible that you missed the catalog_id or the product_retailer_id. Both of those fields are required for this type of message.

1009 - Parameter value is not valid

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.


If you’re trying to send a Single Product Message, it’s possible that you have sent the wrong catalog_id. Please go back to the Commerce Manager and check it again.


If you’re trying to send a Multi-Product Message, check that your product_retailer_id is unique per section. Also make sure the header and body objects are present and have an assigned value.

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 the time. If not, contact Support.

1021 - Bad User

This error occurs when you send a message to yourself.
To resolve, send the message to a 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

2015 - Invalid number of sections

Message request contains below minimum or above the maximum number of sections. See section object for more information.


You need to have at least 1 section object and you can have up to 10.

2016 - Invalid number of rows

There is an invalid number of rows. For List Messages, there must be at least one rows object per section.

2017 - Character Policy Violated

Format character policy has been violated.

2023 - Invalid number of product

The section object has no products or the total product count has exceeded the maximum allowed number.

2024 - Catalog ID not found

The catalog ID you provided either does not exist or does not belong to your WhatsApp Business Account (WABA).

2025 - Catalog ID not linked to API number

The catalog ID you provided is not connected to the phone number you are using to send a message.

2026 - Missing products

Some products provided in your request were not found in the catalog.

2027 - No products found

No products were found in the catalog you provided.

2028 - List all products failed compliance

Only available for businesses in India.

This error is returned when a business sends a Single Product Message with missing and incomplete e-commerce compliance information.

2029 - List some products failed compliance

Only available for businesses in India.

This error is returned when a business sends a Multi-product message with missing and incomplete e-commerce compliance information.

2030 - List mixed products invalid and failed compliance

Only available for businesses in India.

This error is returned when a business sends a Multi-product message where there is a mix of invalid products and products with missing compliance information.

2036 - Invalid Header Structure

Returned when the header object structure is invalid.

2050 - Missing Compliance Info

Only available for businesses in India.

This error is returned when a business has not provided any compliance information. See the Business Compliance endpoint.

For Commerce Manager error codes specific to Indian businesses see the Business Help Center.

WhatsApp Business Management API Error Codes

Message Templates

ErrorDescription

Message Template Limit Exceeded

You have exceeded the maximum number of message templates you can have for this WhatsApp business account.

Phone Migration

ErrorDescriptionSolution

2388103 - Please add this phone number in your WhatsApp 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.

2388103 - The WhatsApp account that this phone number is registered with is not set up correctly.

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.

2388103 - Your WhatsApp account must be approved

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.

2388103 - Your WhatsApp account’s "Messaging For" request must be approved

The destination WABA’s "Messaging For" request must be approved by the client.

Ask your client to accept your "Messaging For" request.

2388103 - This phone number belongs to a different Business Manager account.

The source and destination WABAs must represent the same business.

Migrate your phone number into a WABA that is messaging for the same business as the source WABA.

2388012 - This phone number already exists in your list of phone numbers.

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.

2388103 - There was an error migrating this phone number.

Something went wrong when trying to migrate your phone number.

Try again after some time. If that doesn’t work, contact support.

2388001 - Please confirm ownership of this phone number.

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.

2388091, 2388093 - This phone number isn’t eligible to receive/verify a registration code since it is not being migrated.

Phone ownership verification APIs are not available for this use case.

Verify and register the number using Enterprise Client v1/account and v1/verify APIs.

2388001 - Please ensure two-step authentication is disabled.

Two-step authentication must be disabled for this phone number.

Ask your client to reach out to the source WABA to disable two-step authentication before trying to migrate.

2388103 - Your WhatsApp account does not have a payment account.

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.

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.