WhatsApp Business API Errors

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

On-Premises WhatsApp Business API Client Error Codes
Please refer Meta Developer API for complete client error codes, we have collated the same for quick reference
Error Code
Description
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.
501 - Message type is not currently supported.
Document messages with captions are currently not supported.
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), or
If your business sends commerce messages in India, make sure that you have completed all mandatory business profile and product item fields. For more information, see https://www.facebook.com/business/help/1104628230079278.
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
Message Undeliverable.
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.
1031 - Sender account has been locked
Your account has been locked to send any messages due to an integrity policy violation. See WhatsApp Business Platform Policy Enforcement for information.
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
2014 - Expected Namespace is Empty
This error happens when a template message language pack has not been downloaded yet.
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 Complian endpoint.
​
​

Error Code	Description
`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.
`501` - Message type is not currently supported.	Document messages with captions are currently not supported.
`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), or If your business sends commerce messages in India, make sure that you have completed all mandatory business profile and product item fields. For more information, see https://www.facebook.com/business/help/1104628230079278.
`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 `ID`s 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	Message Undeliverable.
`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.
`1031` - Sender account has been locked	Your account has been locked to send any messages due to an integrity policy violation. See WhatsApp Business Platform Policy Enforcement for information.
`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
`2014` - Expected Namespace is Empty	This error happens when a template message language pack has not been downloaded yet.
`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 Complian endpoint.

DEVELOPER RESOURCES - Previous

Security

Next - Extras

WhatsApp Channel Health

Last modified 6d ago