AUTHORIZATION ERRORS

Code: 0 - AuthException

HTTP Status: 401

Details: We were unable to authenticate the app user.

Solution: Get a new access token. 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.

Code: 3 - API Method

HTTP Status: 500

Details: Capability or permissions issue.

Solution: Use the access token debugger to verify that your app has been granted the permissions required by the endpoint.

Code: 10 - Permission Denied

HTTP Status: 403

Details: Permission is either not granted or has been removed.

Solution: Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. 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.

Code: 190 - Access token has expired

HTTP Status: 401

Details: Your access token has expired.

Solution: Get a new access token.

Code: 200-299 - API Permission

HTTP Status: 403

Details: Permission is either not granted or has been removed.

Solution: Use the access token debugger to verify that your app has been granted the permissions required by the endpoint.

INTEGRITY ERRORS

Code: 368 - Temporarily blocked for policies violations

HTTP Status: 403

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

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

Code: 130497 - Business account is restricted from messaging users in this country.

HTTP Status: 403

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

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

Code: 131031 - Account has been locked

HTTP Status: 403

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

Solution: 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 for the account lock.

TEMPLATE CREATION ERRORS

Code: 2388040 - Character limit exceeded

Details: A field in your template has exceeded the maximum character limit allowed.

Solution: Refer to the error message for specific details on the affected field and its corresponding character limits.

Code: 2388047 - Message header format is incorrect

Details: Your message header contains invalid formatting.

Solution: Refer to the error message for specific details on valid formatting.

Code: 2388072 - Message body format is incorrect

Details: Your message body contains invalid formatting.

Solution: Refer to the error message for specific details on valid formatting.

Code: 2388073 - Message footer format is incorrect

Details: Your message footer contains invalid formatting.

Solution: Refer to the error message for specific details on valid formatting.

Code: 2388293 - Parameters words ratio exceeds limit

Details: This template has too many variables for its length.

Solution: Reduce the number of variables or increase the message length. Refer to the error message for specific details on valid formatting.

Code: 2388299 - Leading or trailing parameters not allowed

Details: Variables cannot be at the start or end of the template.

Solution: Refer to the error message for specific details on valid formatting.

SEND TEMPLATE ERRORS

Code: 2388019 - Message Template Limit Exceeded

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

Solution: A WhatsApp Business Account can have up to 250 message templates. See Template limits.

PHONE MIGRATION ERRORS

Code: 2388001 - Please confirm ownership of this phone number.

Details: Certificate can be downloaded only after confirming ownership of a phone number that is being migrated.

Solution: Register and verify the number.

Code: 2388001 - Please ensure two-step authentication is disabled.

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

Solution: In your WhatsApp Business Manager Settings, turn off two-step verification.

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

Details: The phone number you are trying to migrate is already present in your WhatsApp account.

Solution: Try again with a phone number that is not already present in your WhatsApp account.

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

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

Solution: Register and verify the number.

Code: 2388103 - Cannot migrate phone number.

Details: Webhooks have not been set up for the destination WhatsApp Business account.

Solution: Subscribe your app to webhooks on the destination WhatsApp Business account.

Code: 2388103 - Please add this phone number in your WhatsApp account

Details: This phone number is eligible to be added directly, and does not need to use phone migration APIs.

Solution: Register and verify the number.

Code: 2388103 - Registered name should be present and approved.

Details: The business phone number must have an approved display name and cannot have any associated pending display name change requests.

Solution: Get your business phone number's display name approved.

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

Details: The source WhatsApp Business Account must be approved, and its "messaging on behalf of" must be approved.

Solution: Contact support.

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

Details: Your WhatsApp account must have an active credit line in order to send messages after migration.

Solution: Set up a credit line and share it with the business customer.

Code: 2388103 - There was an error migrating this phone number.

Details: Something went wrong when trying to migrate your phone number.

Solution: Try again after some time. If that doesn't work, contact support.

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

Details: The source and destination WABAs must represent the same business.

Solution: Migrate the phone number into a WhatsApp Business Account that is messaging for the same business as the source WhatsApp Business Account.

Code: 2388103 - Your WhatsApp account must be approved

Details: The destination WhatsApp Business Account must be approved before you can migrate phone numbers.

Solution: Ensure business verification is completed, and the WhatsApp Business Account review status is approved.

Code: 2388103 - Your WhatsApp account's "Messaging For" request must be approved

Details: The destination WhatsApp Business Account "Messaging For" request must be approved by the client.

Solution: Ask your client to accept your "Messaging For" request in the Meta Business Suite.

Code: 2494100 - Account is in maintenance mode.

Details: The business phone number is in maintenance mode.

Solution: Try again in a few minutes.

TEMPLATE INSIGHTS ERRORS

Code: 200005 - Template insights unavailable

Details: Template insights are not available yet for this WhatsApp Business account.

Solution: You are unable to enable template insights for this WhatsApp Business account at the moment.

Code: 200006 - Cannot disable template insights

Details: Invalid operation. Template Insights cannot be disabled once enabled.

Solution: Template insights cannot be disabled once enabled for a WhatsApp Business account.

Code: 200007 - Template Insights not enabled

Details: Template Insights have not been enabled for this WhatsApp Business Account

Solution: To enable template insights, see Confirming template analytics.

WHATSAPP BUSINESS ACCOUNT ERRORS

Code: 2593079 - Template insights unavailable

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

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

Code: 2593085 - Invalid WhatsApp Business Account for OBO Mobility

Details: The WABA is not eligible for OBO ownership transfer.

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

SYNCHRONIZATION ERRORS

Code: 2593107 - Synchronization Request limit exceeded

HTTP Status: 400

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

Solution: You can only call this endpoint once to synchronize the business phone number contacts and once to synchronize its messaging history. Offboard the business customer and re-onboard them.

Code: 2593108 - Synchronization Request made outside of allowed time window

HTTP Status: 400

Details: Synchronization request can only be made within 24 hours of onboarding

Solution: You can only initiate contacts and messaging history synchronization of an onboarded WhatsApp Business app user within 24 hours of onboarding the user. Offboard the user and re-onboard them.

THROTTLING ERRORS

Code: 4 - API Too Many Calls

HTTP Status: 400

Details: The app has reached its API call rate limit.

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

Code: 80007 - Rate limit issues

HTTP Status: 400

Details: The WhatsApp Business Account has reached its rate limit.

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

Code: 130429 - Rate limit hit

HTTP Status: 400

Details: Cloud API message throughput has been reached.

Solution: The app has reached the API's throughput limit. See Throughput. Try again later or reduce the frequency with which the app sends messages.

Code: 131048 - Spam rate limit hit

HTTP Status: 400

Details: Message failed to send because there are restrictions on how many messages can be sent from this phone number.

Solution: Check your quality status in the WhatsApp Manager. See Template limits and Template quality.

Code: 131056 - (Business Account, Consumer Account) pair rate limit hit

HTTP Status: 400

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

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

Code: 133016 - Account register deregister rate limit exceeded

HTTP Status: 400

Details: Registration or Deregistration failed because there were too many attempts for this phone number in a short period of time.

Solution: The business phone number is being blocked because it has reached its registration/deregistration attempt limit. Try again once the number is unblocked.

OTHER ERRORS

Code: 1 - API Unknown

HTTP Status: 400

Details: Invalid request or possible server error.

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

Code: 2 - API Service

HTTP Status: 503

Details: Temporary due to downtime or due to being overloaded.

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

Code: 33 - Parameter value is not valid

HTTP Status: 400

Details: The business phone number has been deleted.

Solution: Verify that the business phone number is correct.

Code: 100 - Invalid parameter

HTTP Status: 400

Details: The request included one or more unsupported or misspelled parameters.

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

Code: 130472 - User's number is part of an experiment

HTTP Status: 400

Details: Message was not sent as part of an experiment.

Solution: See Marketing Message Experiment.

Code: 131000 - Something went wrong

HTTP Status: 500

Details: Message failed to send due to an unknown error.

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

Code: 131005 - Access denied

HTTP Status: 403

Details: Permission is either not granted or has been removed.

Solution: Use the access token debugger to verify that your app has been granted the permissions required by the endpoint.

Code: 131008 - Required parameter is missing

HTTP Status: 400

Details: The request is missing a required parameter.

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

Code: 131009 - Parameter value is not valid

HTTP Status: 400

Details: One or more parameter values are invalid.

Solution: See the endpoint's reference to determine which values are supported for each parameter.

Code: 131016 - Service unavailable

HTTP Status: 500

Details: A service is temporarily unavailable.

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

Code: 131021 - Recipient cannot be sender

HTTP Status: 400

Details: Sender and recipient phone number is the same.

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

Code: 131026 - Message Undeliverable

HTTP Status: 400

Details: Unable to deliver message.

Solution: Using a non-WhatsApp communication method, ask the WhatsApp user to confirm they can send messages, confirm they have accepted latest Terms of Service, and update to latest WhatsApp version.

Code: 131037 - WhatsApp provided number needs display name approval before message can be sent.

HTTP Status: 400

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

Solution: Change the 555 business phone number's display name.

Code: 131042 - Business eligibility payment issue

HTTP Status: 400

Details: There was an error related to your payment method.

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

Code: 131045 - Incorrect certificate

HTTP Status: 500

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

Solution: Register the phone number before trying again.

Code: 131047 - Re-engagement message

HTTP Status: 400

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

Solution: Send the recipient a template message instead.

Code: 131049 - Meta chose not to deliver.

HTTP Status: 400

Details: This message was not delivered to maintain healthy ecosystem engagement.

Solution: If you receive this error code, wait at least 24 hours before resending the template message.

Code: 131050 - User has stopped receipt of marketing messages.

HTTP Status: 400

Details: Unable to deliver the message. This recipient has chosen to stop receiving marketing messages.

Solution: Do not retry sending messages to this user. Subscribe to the user_preferences webhook to be notified.

Code: 131051 - Unsupported message type

HTTP Status: 400

Details: Unsupported message type.

Solution: See Messages for supported message types before trying again.

Code: 131052 - Media download error

HTTP Status: 400

Details: Unable to download the media sent by the user.

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

Code: 131053 - Media upload error

HTTP Status: 400

Details: Unable to upload the media used in the message.

Solution: Inspect any media files that are causing errors and confirm that they are supported. See Supported Media Types.

Code: 131057 - Account in maintenance mode

HTTP Status: 500

Details: Business Account is in maintenance mode.

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

Code: 132000 - Template Param Count Mismatch

HTTP Status: 400

Details: The number of variable parameter values did not match the number of variable parameters defined in the template.

Solution: Make sure the request includes values for all of the parameters required by the template.

Code: 132001 - Template does not exist

HTTP Status: 404

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

Solution: Make sure your template has been approved and the template name and language locale are correct.

Code: 132005 - Template Hydrated Text Too Long

HTTP Status: 400

Details: Translated text is too long.

Solution: Check the WhatsApp Manager to verify that your template has been translated.

Code: 132007 - Template Format Character Policy Violated

HTTP Status: 400

Details: Template content violates a WhatsApp policy.

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

Code: 132012 - Template Parameter Format Mismatch

HTTP Status: 400

Details: Variable parameter values formatted incorrectly.

Solution: The variable parameter values included in the request are not using the format specified in the template.

Code: 132015 - Template is Paused

HTTP Status: 400

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

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

Code: 132016 - Template is Disabled

HTTP Status: 400

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

Solution: Create a new template with different content.

Code: 132068 - Flow is blocked

HTTP Status: 400

Details: Flow is in blocked state.

Solution: Correct the Flow.

Code: 132069 - Flow is throttled

HTTP Status: 400

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

Solution: Correct the Flow.

Code: 133000 - Incomplete Deregistration

HTTP Status: 500

Details: A previous deregistration attempt failed.

Solution: Deregister the number again before registering.

Code: 133004 - Server Temporarily Unavailable

HTTP Status: 503

Details: Server is temporarily unavailable.

Solution: Check the WhatsApp Business Platform Status page to see API status information.

Code: 133005 - Two step verification PIN Mismatch

HTTP Status: 400

Details: Two-step verification PIN incorrect.

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

Code: 133006 - Phone number re-verification needed

HTTP Status: 400

Details: Phone number needs to be verified before registering.

Solution: Verify and register the phone number.

Code: 133008 - Too Many two step verification PIN Guesses

HTTP Status: 400

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

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

Code: 133009 - Two step verification PIN Guessed Too Fast

HTTP Status: 400

Details: Two-step verification PIN was entered too quickly.

Solution: Check the details response value before trying again.

Code: 133010 - Phone number Not Registered

HTTP Status: 400

Details: Phone number not registered on the WhatsApp Business Platform.

Solution: Register the phone number before trying again.

Code: 133015 - Please wait a few minutes before attempting to register this phone number

HTTP Status: 400

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

Solution: Wait 5 minutes before re-trying the request.

Code: 134011 - WhatsApp Payments terms of service has not been accepted

HTTP Status: 400

Details: Message failed to send because WhatsApp Payments terms of service acceptance is pending.

Solution: Accept the WhatsApp Payments terms of service using the link provided in the error message.

Code: 135000 - Generic user error

HTTP Status: 400

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

Solution: See the endpoint's reference to determine if you are querying the endpoint using the correct syntax.

MARKETING MESSAGES API ERRORS

Code: 100 - Invalid parameter

HTTP Status: 400

Details: Message must be a template message.

Solution: You are attempting to send a non-template message. Message type must be template. Try again using a marketing template.

Code: 131009 - Parameter value is not valid

HTTP Status: 400

Details: One or more parameter values are invalid.

Solution: Verify that you are using a valid parameter and try again. Ad syncing may be incomplete. Wait 10 minutes and try again.

Code: 131055 - Method not allowed

HTTP Status: 400

Details: Only marketing template messages are supported.

Solution: You may have attempted to send a non-template message, or an authentication or utility template. Try sending again using a marketing template message.

Code: 134100 - Only marketing messages supported

HTTP Status: 400

Details: You're only able to send marketing messages on this API.

Solution: You are attempting to send a utility or authentication template. Only templates categorized as MARKETING are supported.

Code: 134101 - Your template is still syncing

HTTP Status: 400

Details: When you send a message from a template, the template syncing process can take up to 10 minutes to complete.

Solution: You are attempting to send a newly created template before it has completed Ad synchronization. Wait 10 minutes and try again.

Code: 134102 - Template unavailable for use

HTTP Status: 500

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

Solution: Check your eligibility status. If the WhatsApp Business Account's marketing_messages_lite_api_status value is ONBOARDED, and the problem persists, contact support.

Code: 1752041 - Duplicate Request

Details: Duplicate Request is thrown when a client has already been invited to onboard by any partner.