5. What are the types of error code for failed message ?

The Cloud API is built on the Graph API, so if you are unfamiliar with handling Graph API error responses, see Graph API's error handling documentation.

In general, we recommend that you build your app's error handling logic around code values and details payload properties. These properties and their values are more indicative of the underlying error.

Code titles, which do not have a dedicated property in API error response payloads, are included as part of the message value. However, we recommend that you do not rely on titles for your error handling logic as titles will eventually be deprecated.

Types of Error Codes

Error CodeDescriptionPosssible Solutions


Rate limit issues

The WhatsApp Business Account has reached its rate limit.

See WhatsApp Business Account Rate Limits. Try again later or reduce the frequency or amount of API queries the app is making.


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 and see the Quality-Based Rate Limits documentation for more information.


(Business Account, Consumer Account) pair rate limit hit

Too many messages sent from the sender phone number to the same recipient phone number in a short period of time.

Wait and retry the operation, if you intend to send messages to the same phone number. You can still send messages to a different phone number without waiting


Temporarily blocked for policies violations

The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy.

See the Policy Enforcement document to learn about policy violations and how to resolve them.


Account has been locked

The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy, or we were unable to verify data included in the request against data set on the WhatsApp Business Account (e.g, the two-step pin included in the request is incorrect).

See the Policy Enforcement document to learn about policy violations and how to resolve them.

You can also use the Health Status API, which may provide additional insight into the reason or reasons for the account lock.


Invalid parameter

The request included one or more unsupported or misspelled parameters.

See the endpoint's reference to determine which parameters are supported and how they are spelled.

Ensure when setting the business public key, it is a valid 2048-bit RSA public key in PEM format.

Ensure there is no mismatch between the phone number id you are registering and a previously stored phone number id.


User's number is part of an experiment

Message was not sent as part of an experiment.


Something went wrong

Message failed to send due to an unknown error.

When setting a business public key, it either failed to calculate the signature, call the GraphQL endpoint, or the GraphQL endpoint returned an error.

Try again. If the error persists, open a Direct Support ticket.


Message Undeliverable

Unable to deliver message. Reasons can include:

  • The recipient phone number is not a WhatsApp phone number.

  • Sending an authentication template to a WhatsApp user who has a +91 country calling code (India). Authentication templates currently cannot be sent to WhatsApp users in India.

  • Recipient has not accepted our new Terms of Service and Privacy Policy.

  • Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:

    • Android:

    • SMBA:

    • iOS:

    • SMBI:

    • KaiOS: 2.2130.10

    • Web: 2.2132.6

  • The message was not delivered to create a high quality user experience. See Per-User Marketing Template Message Limits.

Using a non-WhatsApp communication method, ask the WhatsApp user to:

  • Confirm that they can actually send a message to your WhatsApp business phone number.

  • Confirm that your WhatsApp business phone number is not in their list of blocked numbers (Settings > Privacy > Blocked or Blocked contacts).

  • Confirm that they have accepted our latest Terms of Service (Settings > Help, or Settings > Application information will prompt them to accept the latest terms/policies if they haven't done so already)

  • Update to the latest version of the WhatsApp client.


Re-engagement message

More than 24 hours have passed since the recipient last replied to the sender number.

Send the recipient a business-initiated message using a message template instead.


Template does not exist

The template does not exist in the specified language or the template has not been approved.

Make sure your template has been approved and the template name and language locale are correct. Please ensure you follow message template guidelines.


Generic user error

Message failed to send because of an unknown error with your request parameters.

See the endpoint's reference to determine if you are querying the endpoint using the correct syntax. Contact customer support if you continue receiving this error code in response.

Last updated