Error codes

The Cloud API is built on the Graph API, so if you are unfamiliar with handling Graph API error responses, see the Graph API 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.

Receiving Errors: Synchronous and Asynchronous

Cloud API errors are returned either synchronously as a Graph API response, asynchronously via Webhook, or sometimes through both methods.

It is a good practice when working with Cloud API that you monitor both the Graph API response and the messages webhook for error handling. If you are subscribed to the messages webhook field, you will receive notification of errors as they occur for supported asynchronous error types.

Error response webhooks and syntax

Cloud API errors can be surfaced in the following webhook objects:

entry.changes.value.errors
entry.changes.value.messages.errors

Error response syntax

{
  "error": {
    "message": "<MESSAGE>",
    "type": "<TYPE>",
    "code": <CODE>,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "<DETAILS>"
    },
    "error_subcode": <ERROR_SUBCODE>,
    "fbtrace_id": "<FBTRACE_ID>"
  }
}

Error response contents

Property	Value Type	Description
`code`	Integer	Error code. We recommend that you build your app's error handling around error codes instead of subcodes or HTTP response status codes.
`details`	String	Error description and a description of the most likely reason for the error. May also contain information on how to address the error, such as which parameter is invalid or what values are acceptable.
`error_subcode`	Integer	Deprecated. Will not be returned in v16.0+ responses. Graph API subcode. Not all responses will include a subcode, so we recommend that you build your error handling logic around `code` and `details` properties instead.
`fbtrace_id`	String	Trace ID you can include when contacting Direct Support. The ID may help us debug the error.
`message`	String	Combination of the error code and its title. For example: `(#130429) Rate limit hit`.
`messaging_product`	String	Messaging product. This will always be the string `whatsapp` for Cloud API responses.
`type`	String	Error type.

Example response

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
        "messaging_product": "whatsapp", 
        "details": "Cloud API message throughput has been reached."
    },
    "error_subcode": 2494055,
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

Authorization errors

Code	Details	Possible reasons and solutions	HTTP Status Code
`0` AuthException	We were unable to authenticate the app user.	Typically this means the included access token has expired, been invalidated, or the app user has changed a setting to prevent all apps from accessing their data. We recommend that you get a new access token.	`401` Unauthorized
`3` API Method	Capability or permissions issue.	Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Authentication and Authorization Errors.	`500` Internal Server Error
`10` Permission Denied	Permission is either not granted or has been removed.	Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Authentication and Authorization Errors. For WhatsApp Flows with Endpoint - ensure that the phone number used to set the business public key is allowlisted. Check the eligibility requirements for the API that you are trying to access. If you are not eligible to access the endpoints, you will receive this error code.	`403` Forbidden
`190` Access token has expired	Your access token has expired.	Get a new access token.	`401` Unauthorized
`200-299` API Permission	Permission is either not granted or has been removed.	Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Authentication and Authorization Errors.	`403` Forbidden

Integrity errors

Code Details Possible reasons and solutions HTTP Status Code

Code	Details	Possible reasons and solutions	HTTP Status Code
`368` 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.	`403` Forbidden
`130497` Business account is restricted from messaging users in this country.	The WhatsApp Business Account is restricted from messaging to users in certain countries.	See WhatsApp Business Messaging Policy for details on allowed countries for messaging in your business category.	`403` Forbidden
`131031` 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.	`403` Forbidden

368

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.

403

Forbidden

130497

Business account is restricted from messaging users in this country.

The WhatsApp Business Account is restricted from messaging to users in certain countries.

See WhatsApp Business Messaging Policy for details on allowed countries for messaging in your business category.

403

Forbidden

131031

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.

403

Forbidden

Template creation errors

Error	Description	Possible Solution
`2388040` - Character limit exceeded	A field in your template has exceeded the maximum character limit allowed.	Refer to the error message for specific details on the affected field and its corresponding character limits.
`2388047` - Message header format is incorrect	Your message header contains invalid formatting.	Refer to the error message for specific details on valid formatting.
`2388072` - Message body format is incorrect	Your message body contains invalid formatting.	Refer to the error message for specific details on valid formatting.
`2388073` - Message footer format is incorrect	Your message footer contains invalid formatting.	Refer to the error message for specific details on valid formatting.
`2388293` - Parameters words ratio exceeds limit	This template has too many variables for its length. Reduce the number of variables or increase the message length.	Refer to the error message for specific details on valid formatting.
`2388299` - Leading or trailing parameters not allowed	Variables cannot be at the start or end of the template.	Refer to the error message for specific details on valid formatting.

Send template errors

Error	Description	Possible Solution
`2388019` - Message Template Limit Exceeded	You have exceeded the maximum number of message templates you can have for this WhatsApp business account.	A WhatsApp Business Account can have up to 250 message templates. See Template limits.

Phone migration errors

Error	Description	Possible Solution
`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, register and and verify the number.
`2388001` - Please ensure two-step authentication is disabled.	Two-step authentication must be disabled for this phone number.	In your WhatsApp Business Manager Settings, turn off two-step verification.
`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.
`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.	Register and verify the number.
`2388103` - Cannot migrate phone number.	Webhooks have not been set up for the destination WhatsApp Business account.	Subscribe your app to webhooks on the destination WhatsApp Business account.
`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.	Register and verify the number.
`2388103` - Registered name should be present and approved.	The business phone number must have an approved display name (`name_status` is `APPROVED`) and cannot have any associated pending display name change requests.	Get your business phone number's display name approved.
`2388103` - The WhatsApp account that this phone number is registered with is not set up correctly.	The source WhatsApp Business Account must be approved, and its "messaging on behalf of" must be approved.	The WhatsApp Business Account may be using the now deprecated On-Behalf-Of ownership model. Contact support.
`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.	Set up a credit line and share it with the business customer.
`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.
`2388103` - This phone number belongs to a different Business Manager account.	The source and destination WABAs must represent the same business.	Migrate the phone number into a WhatsApp Business Account that is messaging for the same business as the source WhatsApp Business Account.
`2388103` - Your WhatsApp account must be approved	The destination WhatsApp Business Account must be approved before you can migrate phone numbers.	Ensure business verification is completed, and the WhatsApp Business Account review status is approved.
`2388103` - Your WhatsApp account’s "Messaging For" request must be approved	The destination WhatsApp Business Account "Messaging For" request must be approved by the client.	Ask your client to accept your "Messaging For" request in the Meta Business Suite.
`2494100` - Account is in maintenance mode.	The business phone number is in maintenance mode.	Try again in a few minutes.

Template insights errors

Error	Description	Possible Solution
`200005` - Template insights unavailable	Template insights are not available yet for this WhatsApp Business account.	You are unable to enable template insights for this WhatsApp Business account at the moment.
`200006` - Cannot disable template insights	Invalid operation. Template Insights cannot be disabled once enabled.	Template insights cannot be disabled once enabled for a WhatsApp Business account.
`200007` - Template Insights not enabled	Template Insights have not been enabled for this WhatsApp Business Account	To enable template insights, see Confirming template analytics.

WhatsApp Business Account errors

Error Description Possible Solution

Error	Description	Possible Solution
`2593079` Template insights unavailable	This WABA has already been marked for migration to a different solution ID	The OBO account ownership model is now deprecated. Please contact support.
`2593085` Invalid WhatsApp Business Account for OBO Mobility	The WABA is not eligible for OBO ownership transfer. Possible reasons could be: The WABA is already owned by the business customer (i.e. already uses the WABA Sharing model). The business customer has yet to accept the OBO request in the Meta Business Suite.	Note that the OBO account ownership model is now deprecated. Please contact support.

2593079

Template insights unavailable

This WABA has already been marked for migration to a different solution ID

The OBO account ownership model is now deprecated. Please contact support.

2593085

Invalid WhatsApp Business Account for OBO Mobility

The WABA is not eligible for OBO ownership transfer. Possible reasons could be:

The WABA is already owned by the business customer (i.e. already uses the WABA Sharing model).
The business customer has yet to accept the OBO request in the Meta Business Suite.

Note that the OBO account ownership model is now deprecated. Please contact support.

Synchronization errors

Code Details Possible reasons and solutions HTTP Status Code

Code	Details	Possible reasons and solutions	HTTP Status Code
`2593107` Synchronization Request limit exceeded	You have exceeded the maximum number of times to call the synchronization api for this phone number.	You can only call this endpoint once to synchronize the business phone number contacts and once to synchronize its messaging history. See Onboarding business app users. Offboard the business customer and re-onboard them.	`400` Bad Request
`2593108` Synchronization Request made outside of allowed time window	Synchronization request can only be made within 24 hours of onboarding	You can only initiate contacts and messaging history synchronization of an onboarded WhatsApp Business app user within 24 hours of onboarding the user. See Onboarding business app users. Offboard the user and re-onboard them.	`400` Bad Request

2593107

Synchronization Request limit exceeded

You have exceeded the maximum number of times to call the synchronization api for this phone number.

You can only call this endpoint once to synchronize the business phone number contacts and once to synchronize its messaging history. See Onboarding business app users.

Offboard the business customer and re-onboard them.

400

Bad Request

2593108

Synchronization Request made outside of allowed time window

Synchronization request can only be made within 24 hours of onboarding

You can only initiate contacts and messaging history synchronization of an onboarded WhatsApp Business app user within 24 hours of onboarding the user. See Onboarding business app users.

Offboard the user and re-onboard them.

400

Bad Request

Throttling errors

Code	Details	Possible reasons and solutions	HTTP Status Code
`4` API Too Many Calls	The app has reached its API call rate limit.	Load the app in the App Dashboard and view the Application Rate Limit section to verify that the app has reached its rate limit. If it has, try again later or reduce the frequency or amount of API queries the app is making.	`400` Bad Request
`80007` 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.	`400` Bad Request
`130429` Rate limit hit	Cloud API message throughput has been reached.	The app has reached the API's throughput limit. See Throughput. Try again later or reduce the frequency with which the app sends messages.	`400` Bad Request
`131048` 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 Template limits and Template quality.	`400` Bad Request
`131056` (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	`400` Bad Request
`133016` Account register deregister rate limit exceeded	Registration or Deregistration failed because there were too many attempts for this phone number in a short period of time	The business phone number is being blocked because it has reached its registration/deregistration attempt limit. Try again once the number is unblocked. See "Limitations" in the Registration document.	`400` Bad Request

Other errors

Code Details Possible reasons and solutions HTTP Status Code

Code	Details	Possible reasons and solutions	HTTP Status Code
`1` API Unknown	Invalid request or possible server error.	Check the WhatsApp Business Platform Status page to see API status information. If there are no server outages, check the endpoint reference and verify that your request is formatted correctly and meets all endpoint requirements.	`400` Bad Request
`2` API Service	Temporary due to downtime or due to being overloaded.	Check the WhatsApp Business Platform Status page to see API status information before trying again.	`503` Service Unavailable
`33` Parameter value is not valid	The business phone number has been deleted.	Verify that the business phone number is correct.	`400` Bad Request
`100` 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. For WhatsApp Flows with Endpoint - 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. Ensure your parameter is under any length restriction for the type.	`400` Bad Request
`130472` User's number is part of an experiment	Message was not sent as part of an experiment.	See Marketing Message Experiment.	`400` Bad Request
`131000` Something went wrong	Message failed to send due to an unknown error.	Try again. If the error persists, open a Direct Support ticket. For WhatsApp Flows with Endpoint - when setting a business public key, it either failed to calculate the signature, call the GraphQL endpoint, or the GraphQL endpoint returned an error.	`500` Internal Server Error
`131005` Access denied	Permission is either not granted or has been removed.	Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Authentication and authorization errors.	`403` Forbidden
`131008` Required parameter is missing	The request is missing a required parameter.	See the endpoint's reference to determine which parameters are required.	`400` Bad Request
`131009` Parameter value is not valid	One or more parameter values are invalid.	See the endpoint's reference to determine which values are supported for each parameter, and see Phone Numbers to learn how to add a phone number to a WhatsApp Business Account.	`400` Bad Request
`131016` Service unavailable	A service is temporarily unavailable.	Check the WhatsApp Business Platform Status page to see API status information before trying again.	`500` Internal Server Error
`131021` Recipient cannot be sender	Sender and recipient phone number is the same.	Send a message to a phone number different from the sender.	`400` Bad Request
`131026` Message Undeliverable	Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number. 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: 2.21.15.15 SMBA: 2.21.15.15 iOS: 2.21.170.4 SMBI: 2.21.170.4 KaiOS: 2.2130.10 Web: 2.2132.6	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 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.	`400` Bad Request
`131037` WhatsApp provided number needs display name approval before message can be sent.	The 555 business phone number used to send the request does not have an approved display name.	Change the 555 business phone number's display name. Also see our How to change your WhatsApp Business display name Help Center article.	`400` Bad Request
`131042` Business eligibility payment issue	There was an error related to your payment method.	See About Billing For Your WhatsApp Business Account and verify that you have set up billing correctly. Common problems: Payment account is not attached to a WhatsApp Business Account Credit line is over the limit Credit line (Payment Account) not set or active WhatsApp Business Account is deleted WhatsApp Business Account is suspended Timezone not set Currency not set MessagingFor request (On Behalf Of) is pending or declined	`400` Bad Request
`131045` Incorrect certificate	Message failed to send due to a phone number registration error.	Register the phone number before trying again.	`500` Internal Server Error
`131047` Re-engagement message	More than 24 hours have passed since the recipient last replied to the sender number.	Send the recipient a template message instead.	`400` Bad Request
`131049` Meta chose not to deliver.	This message was not delivered to maintain healthy ecosystem engagement.	If you do receive this error code and suspect it is due to the limit, wait at least 24 hours before resending the template message. Doing so will only result in another error response since the limit may be in effect for differing periods of time. See Per-User Marketing Template Message Limits for additional information.	`400` Bad Request
`131050` User has stopped receipt of marketing messages.	Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business.	Do not retry sending messages to this user as they will not be received. To be notified whenever a WhatsApp user stops or resumes delivery of marketing template messages from your business, subscribe to the user_preferences webhook.	`400` Bad Request
`131051` Unsupported message type	Unsupported message type.	See Messages for supported message types before trying again with a supported message type.	`400` Bad Request
`131052` Media download error	Unable to download the media sent by the user.	We were unable to download media included in the WhatsApp user's message. For more information, refer to the `error.error_data.details` value in any messages webhooks triggered when this message was received. Ask the WhatsApp user to send you the media file using a non-WhatsApp method.	`400` Bad Request
`131053` Media upload error	Unable to upload the media used in the message.	We were unable to upload the media for one or more reasons, such as an unsupported media type. For more information, refer to the `error.error_data.details` value in any messages webhooks triggered when this message fails to send. We recommend that you inspect any media files that are causing errors and confirm that they are in fact supported. For example, in UNIX you can use file inspection via the command line to determine its MIME type: `file -I rejected-file.mov` You can then confirm if its MIME type is supported. See Supported Media Types.	`400` Bad Request
`131057` Account in maintenance mode	Business Account is in maintenance mode	The WhatsApp Business Account is in maintenance mode. One reason for this could be that the account is undergoing a throughput upgrade.	`500` Bad Request
`132000` Template Param Count Mismatch	The number of variable parameter values included in the request did not match the number of variable parameters defined in the template.	See our Templates document to learn about parameters and make sure the request includes values for all of the parameters required by the template.	`400` Bad Request
`132001` 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. See our Templates document to learn more about templates.	`404` Not Found
`132005` Template Hydrated Text Too Long	Translated text is too long.	Check the WhatsApp Manager to verify that your template has been translated. See our Template quality document to learn how to check the status of your template.	`400` Bad Request
`132007` Template Format Character Policy Violated	Template content violates a WhatsApp policy.	See our Template review document to learn about possible reasons for the violation.	`400` Bad Request
`132012` Template Parameter Format Mismatch	Variable parameter values formatted incorrectly.	The variable parameter values included in the request are not using the format specified in the template. See our Templates document to learn more about template parameters and formats.	`400` Bad Request
`132015` Template is Paused	Template is paused due to low quality so it cannot be sent in a template message.	Edit the template to improve its quality and try again once it is approved.	`400` Bad Request
`132016` Template is Disabled	Template has been paused too many times due to low quality and is now permanently disabled.	Create a new template with different content.	`400` Bad Request
`132068` Flow is blocked	Flow is in blocked state.	Correct the Flow	`400` Bad Request
`132069` Flow is throttled	Flow is in throttled state and 10 messages using this flow were already sent in the last hour.	Correct the Flow	`400` Bad Request
`133000` Incomplete Deregistration	A previous deregistration attempt failed.	Deregister the number again before registering.	`500` Internal Server Error
`133004` Server Temporarily Unavailable	Server is temporarily unavailable.	Check the WhatsApp Business Platform Status page to see API status information and check the response `details` value before trying again.	`503` Service Unavailable
`133005` Two step verification PIN Mismatch	Two-step verification PIN incorrect.	Verify that the two-step verification PIN included in the request is correct. To reset the PIN, disable two-step verification, then set a new PIN. See Two-step verification.	`400` Bad Request
`133006` Phone number re-verification needed	Phone number needs to be verified before registering.	Verify and register the phone number.	`400` Bad Request
`133008` Too Many two step verification PIN Guesses	Too many two-step verification PIN guesses for this phone number.	Try again after the amount of time specified in the `details` response value.	`400` Bad Request
`133009` Two step verification PIN Guessed Too Fast	Two-step verification PIN was entered too quickly.	Check the `details` response value before trying again.	`400` Bad Request
`133010` Phone number Not Registered	Phone number not registered on the WhatsApp Business Platform.	Register the phone number before trying again.	`400` Bad Request
`133015` Please wait a few minutes before attempting to register this phone number	The phone number you are attempting to register was recently deleted, and deletion has not yet completed.	Wait 5 minutes before re-trying the request.	`400` Bad Request
`134011` WhatsApp Payments terms of service has not been accepted	Message failed to send because WhatsApp Payments terms of service acceptance is pending for this WhatsApp Business Account.	Accept the WhatsApp Payments terms of service using the link provided in the error message before trying again.	`400` Bad Request
`135000` 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.	`400` Bad Request

1

API Unknown

Invalid request or possible server error.

Check the WhatsApp Business Platform Status page to see API status information. If there are no server outages, check the endpoint reference and verify that your request is formatted correctly and meets all endpoint requirements.

400

Bad Request

2

API Service

Temporary due to downtime or due to being overloaded.

Check the WhatsApp Business Platform Status page to see API status information before trying again.

503

Service Unavailable

33

Parameter value is not valid

The business phone number has been deleted.

Verify that the business phone number is correct.

400

Bad Request

100

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.

For WhatsApp Flows with Endpoint - 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.

Ensure your parameter is under any length restriction for the type.

400

Bad Request

130472

User's number is part of an experiment

Message was not sent as part of an experiment.

See Marketing Message Experiment.

400

Bad Request

131000

Something went wrong

Message failed to send due to an unknown error.

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

For WhatsApp Flows with Endpoint - when setting a business public key, it either failed to calculate the signature, call the GraphQL endpoint, or the GraphQL endpoint returned an error.

500

Internal Server Error

131005

Access denied

Permission is either not granted or has been removed.

Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Authentication and authorization errors.

403

Forbidden

131008

Required parameter is missing

The request is missing a required parameter.

See the endpoint's reference to determine which parameters are required.

400

Bad Request

131009

Parameter value is not valid

One or more parameter values are invalid.

See the endpoint's reference to determine which values are supported for each parameter, and see Phone Numbers to learn how to add a phone number to a WhatsApp Business Account.

400

Bad Request

131016

Service unavailable

A service is temporarily unavailable.

Check the WhatsApp Business Platform Status page to see API status information before trying again.

500

Internal Server Error

131021

Recipient cannot be sender

Sender and recipient phone number is the same.

Send a message to a phone number different from the sender.

400

Bad Request

131026

Message Undeliverable

Unable to deliver message. Reasons can include:

The recipient phone number is not a WhatsApp phone number.
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: 2.21.15.15
- SMBA: 2.21.15.15
- iOS: 2.21.170.4
- SMBI: 2.21.170.4
- KaiOS: 2.2130.10
- Web: 2.2132.6

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 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.

400

Bad Request

131037

WhatsApp provided number needs display name approval before message can be sent.

The 555 business phone number used to send the request does not have an approved display name.

Change the 555 business phone number's display name. Also see our How to change your WhatsApp Business display name Help Center article.

400

Bad Request

131042

Business eligibility payment issue

There was an error related to your payment method.

See About Billing For Your WhatsApp Business Account and verify that you have set up billing correctly.

Common problems:

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

400

Bad Request

131045

Incorrect certificate

Message failed to send due to a phone number registration error.

500

Internal Server Error

131047

Re-engagement message

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

Send the recipient a template message instead.

400

Bad Request

131049

Meta chose not to deliver.

This message was not delivered to maintain healthy ecosystem engagement.

If you do receive this error code and suspect it is due to the limit, wait at least 24 hours before resending the template message. Doing so will only result in another error response since the limit may be in effect for differing periods of time.

See Per-User Marketing Template Message Limits for additional information.

400

Bad Request

131050

User has stopped receipt of marketing messages.

Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business.

Do not retry sending messages to this user as they will not be received. To be notified whenever a WhatsApp user stops or resumes delivery of marketing template messages from your business, subscribe to the user_preferences webhook.

400

Bad Request

131051

Unsupported message type

Unsupported message type.

See Messages for supported message types before trying again with a supported message type.

400

Bad Request

131052

Media download error

Unable to download the media sent by the user.

We were unable to download media included in the WhatsApp user's message. For more information, refer to the error.error_data.details value in any messages webhooks triggered when this message was received.

Ask the WhatsApp user to send you the media file using a non-WhatsApp method.

400

Bad Request

131053

Media upload error

Unable to upload the media used in the message.

We were unable to upload the media for one or more reasons, such as an unsupported media type.

For more information, refer to the error.error_data.details value in any messages webhooks triggered when this message fails to send.

We recommend that you inspect any media files that are causing errors and confirm that they are in fact supported. For example, in UNIX you can use file inspection via the command line to determine its MIME type:

file -I rejected-file.mov

You can then confirm if its MIME type is supported. See Supported Media Types.

400

Bad Request

131057

Account in maintenance mode

Business Account is in maintenance mode

The WhatsApp Business Account is in maintenance mode. One reason for this could be that the account is undergoing a throughput upgrade.

500

Bad Request

132000

Template Param Count Mismatch

The number of variable parameter values included in the request did not match the number of variable parameters defined in the template.

See our Templates document to learn about parameters and make sure the request includes values for all of the parameters required by the template.

400

Bad Request

132001

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. See our Templates document to learn more about templates.

404

Not Found

132005

Template Hydrated Text Too Long

Translated text is too long.

Check the WhatsApp Manager to verify that your template has been translated. See our Template quality document to learn how to check the status of your template.

400

Bad Request

132007

Template Format Character Policy Violated

Template content violates a WhatsApp policy.

See our Template review document to learn about possible reasons for the violation.

400

Bad Request

132012

Template Parameter Format Mismatch

Variable parameter values formatted incorrectly.

The variable parameter values included in the request are not using the format specified in the template. See our Templates document to learn more about template parameters and formats.

400

Bad Request

132015

Template is Paused

Template is paused due to low quality so it cannot be sent in a template message.

Edit the template to improve its quality and try again once it is approved.

400

Bad Request

132016

Template is Disabled

Template has been paused too many times due to low quality and is now permanently disabled.

Create a new template with different content.

400

Bad Request

132068

Flow is blocked

Flow is in blocked state.

Correct the Flow

400

Bad Request

132069

Flow is throttled

Flow is in throttled state and 10 messages using this flow were already sent in the last hour.

Correct the Flow

400

Bad Request

133000

Incomplete Deregistration

A previous deregistration attempt failed.

Deregister the number again before registering.

500

Internal Server Error

133004

Server Temporarily Unavailable

Server is temporarily unavailable.

Check the WhatsApp Business Platform Status page to see API status information and check the response details value before trying again.

503

Service Unavailable

133005

Two step verification PIN Mismatch

Two-step verification PIN incorrect.

Verify that the two-step verification PIN included in the request is correct.

To reset the PIN, disable two-step verification, then set a new PIN. See Two-step verification.

400

Bad Request

133006

Phone number re-verification needed

Phone number needs to be verified before registering.

Verify and register the phone number.

400

Bad Request

133008

Too Many two step verification PIN Guesses

Too many two-step verification PIN guesses for this phone number.

Try again after the amount of time specified in the details response value.

400

Bad Request

133009

Two step verification PIN Guessed Too Fast

Two-step verification PIN was entered too quickly.

Check the details response value before trying again.

400

Bad Request

133010

Phone number Not Registered

Phone number not registered on the WhatsApp Business Platform.

400

Bad Request

133015

Please wait a few minutes before attempting to register this phone number

The phone number you are attempting to register was recently deleted, and deletion has not yet completed.

Wait 5 minutes before re-trying the request.

400

Bad Request

134011

WhatsApp Payments terms of service has not been accepted

Message failed to send because WhatsApp Payments terms of service acceptance is pending for this WhatsApp Business Account.

Accept the WhatsApp Payments terms of service using the link provided in the error message before trying again.

400

Bad Request

135000

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.

400

Bad Request

Marketing Messages API for WhatsApp Error codes

MM API for WhatsApp uses the same error codes as Cloud API, with a few additions listed below.

Example

{
  "error": {
    "message": "(#100) Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Message must be a template message."
    },
    "fbtrace_id": "Ak6nxJSySLEJz32Ps-QiZ1t"
  }
}

Codes

Code	Message	Details	Possible reasons and solutions	HTTP status code
`100`	`(#100) Invalid parameter`	`Message must be a template message.`	You are attempting to send a non-template message. Message type must be `template`. Try again using a marketing template.	400 Bad Request
`131009`	`(#131009) Parameter value is not valid`	`One or more parameter values are invalid.`	You may be using an invalid parameter. Verify that you are using a valid parameter and try again. Ad syncing may be incomplete. Wait 10 minutes and try again. If the issue persists, contact support.	400 Bad Request
`131055`	`(#131055) Method not allowed`	`Only marketing template messages are supported`	You may have attempted to send a non-template message, or an authentication or utility template. Try sending again using a marketing template message.	400 Bad Request
`134100`	`(#134100) Only marketing messages supported`	`You're only able to send marketing messages on this API.`	Will be available with Graph API version 23.0. You are attempting to send a utility or authentication template. Only templates categorized as `MARKETING` are supported.	400 Bad Request
`134101`	`(#134101) Your template is still syncing`	`When you send a message from a template, the template syncing process can take up to 10 minutes to complete. Wait a few minutes, and then try sending your message again.`	Will be available with Graph API version 23.0. You are attempting to send a newly created template before it has completed Ad synchronization. Ad synchronization can take up to 10 minutes. Wait 10 minutes and try again.	400 Bad Request
`134102`	`(#134102) Template unavailable for use`	`Please check your eligibility status to ensure you are onboarded (https://developers.facebook.com/docs/whatsapp/marketing-messages-api-for-whatsapp/onboarding#ensure-you-are-eligible-to-onboard) or contact Meta's customer support.`	Will be available with Graph API version 23.0. We were unable to complete Ad synchronization for the template you are attempting to send, or you may not be eligible for MM API for WhatsApp. Check your eligibility status. If the WhatsApp Business Account's `marketing_messages_lite_api_status` value is `ONBOARDED`, and the problem persists, please contact support.	500 Internal Server Error
`1752041`	`(#1752041) Duplicate Request`	`Duplicate Request is thrown when a client has already been invited to onboard by any partner.`	Onboarding requests are limited to one per business customer, with only the first partner to call the intent API able to successfully submit the request. When a client is onboarded, all of their eligible WhatsApp Business Accounts (WABAs) are included in the process automatically. If you receive an error indicating that the onboarding request has already been made, no further action is required, as all eligible WABAs for that client will be onboarded without additional steps.	400 Bad Request