📋 WhatsApp Business API Error Codes

Complete Reference Guide for Troubleshooting

35
Total Error Codes
6
HTTP Status Types
Code: 1 400 Bad Request

API Unknown

Details: Invalid request or possible server error.
💡 Possible Reasons & Solutions
  • Check the WhatsApp Business Platform Status page to see API status information
  • If there are no server outages, check the endpoint reference
  • Verify that your request is formatted correctly and meets all endpoint requirements
Code: 2 503 Service Unavailable

API Service

Details: Temporary due to downtime or due to being overloaded.
💡 Possible Reasons & Solutions
Check the WhatsApp Business Platform Status page to see API status information before trying again.
Code: 33 400 Bad Request

Parameter value is not valid

Details: The business phone number has been deleted.
💡 Possible Reasons & Solutions
Verify that the business phone number is correct.
Code: 100 400 Bad Request

Invalid parameter

Details: The request included one or more unsupported or misspelled parameters.
💡 Possible Reasons & Solutions
  • 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
Code: 130472 400 Bad Request

User's number is part of an experiment

Details: Message was not sent as part of an experiment.
💡 Possible Reasons & Solutions
See Marketing Message Experiment documentation.
Code: 131000 500 Internal Server Error

Something went wrong

Details: Message failed to send due to an unknown error.
💡 Possible Reasons & Solutions
  • 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
Code: 131005 403 Forbidden

Access denied

Details: Permission is either not granted or has been removed.
💡 Possible Reasons & Solutions
Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Authentication and authorization errors.
Code: 131008 400 Bad Request

Required parameter is missing

Details: The request is missing a required parameter.
💡 Possible Reasons & Solutions
See the endpoint's reference to determine which parameters are required.
Code: 131009 400 Bad Request

Parameter value is not valid

Details: One or more parameter values are invalid.
💡 Possible Reasons & Solutions
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.
Code: 131016 500 Internal Server Error

Service unavailable

Details: A service is temporarily unavailable.
💡 Possible Reasons & Solutions
Check the WhatsApp Business Platform Status page to see API status information before trying again.
Code: 131021 400 Bad Request

Recipient cannot be sender

Details: Sender and recipient phone number is the same.
💡 Possible Reasons & Solutions
Send a message to a phone number different from the sender.
Code: 131026 400 Bad Request

Message Undeliverable

Details: Unable to deliver message.
💡 Possible Reasons & Solutions
  • 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 minimum versions:
    • 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
  • Ask the WhatsApp user to confirm they can send a message to your business number
  • Ask them to accept the latest Terms of Service
  • Ask them to update to the latest WhatsApp client version
Code: 131037 400 Bad Request

Display name approval needed

Details: WhatsApp provided number needs display name approval before message can be sent.
💡 Possible Reasons & Solutions
Change the 555 business phone number's display name. See the "How to change your WhatsApp Business display name" Help Center article.
Code: 131042 400 Bad Request

Business eligibility payment issue

Details: There was an error related to your payment method.
💡 Possible Reasons & Solutions
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 or suspended
  • Timezone not set
  • Currency not set
  • MessagingFor request (On Behalf Of) is pending or declined
See "About Billing For Your WhatsApp Business Account" and verify billing setup.
Code: 131045 500 Internal Server Error

Incorrect certificate

Details: Message failed to send due to a phone number registration error.
💡 Possible Reasons & Solutions
Register the phone number before trying again.
Code: 131047 400 Bad Request

Re-engagement message

Details: More than 24 hours have passed since the recipient last replied to the sender number.
💡 Possible Reasons & Solutions
Send the recipient a template message instead.
Code: 131049 400 Bad Request

Meta chose not to deliver

Details: This message was not delivered to maintain healthy ecosystem engagement.
💡 Possible Reasons & Solutions
  • If you receive this error code, wait at least 24 hours before resending the template message
  • The limit may be in effect for differing periods of time
  • See Per-User Marketing Template Message Limits for additional information
Code: 131050 400 Bad Request

User has stopped receipt of marketing messages

Details: This recipient has chosen to stop receiving marketing messages on WhatsApp from your business.
💡 Possible Reasons & Solutions
  • Do not retry sending messages to this user as they will not be received
  • To be notified when users stop or resume delivery, subscribe to the user_preferences webhook
Code: 131051 400 Bad Request

Unsupported message type

Details: Unsupported message type.
💡 Possible Reasons & Solutions
See Messages documentation for supported message types before trying again with a supported message type.
Code: 131052 400 Bad Request

Media download error

Details: Unable to download the media sent by the user.
💡 Possible Reasons & Solutions
  • 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
  • Ask the WhatsApp user to send you the media file using a non-WhatsApp method
Code: 131053 400 Bad Request

Media upload error

Details: Unable to upload the media used in the message.
💡 Possible Reasons & Solutions
  • We were unable to upload the media (unsupported media type, etc.)
  • Inspect media files and confirm they are supported
  • In UNIX, use: file -I rejected-file.mov to check MIME type
  • Confirm if MIME type is supported - see Supported Media Types
Code: 131057 400 Bad Request

Account in maintenance mode

Details: Business Account is in maintenance mode.
💡 Possible Reasons & Solutions
The WhatsApp Business Account is in maintenance mode. One reason could be that the account is undergoing a throughput upgrade. Wait and try again later.
Code: 132000 400 Bad Request

Template Param Count Mismatch

Details: The number of variable parameter values included in the request did not match the number of variable parameters defined in the template.
💡 Possible Reasons & Solutions
See Templates documentation to learn about parameters and make sure the request includes values for all required parameters.
Code: 132001 404 Not Found

Template does not exist

Details: The template does not exist in the specified language or the template has not been approved.
💡 Possible Reasons & Solutions
Make sure your template has been approved and the template name and language locale are correct. See Templates documentation.
Code: 132005 400 Bad Request

Template Hydrated Text Too Long

Details: Translated text is too long.
💡 Possible Reasons & Solutions
Check the WhatsApp Manager to verify that your template has been translated. See Template quality documentation.
Code: 132007 400 Bad Request

Template Format Character Policy Violated

Details: Template content violates a WhatsApp policy.
💡 Possible Reasons & Solutions
See Template review documentation to learn about possible reasons for the violation.
Code: 132012 400 Bad Request

Template Parameter Format Mismatch

Details: Variable parameter values formatted incorrectly.
💡 Possible Reasons & Solutions
The variable parameter values are not using the format specified in the template. See Templates documentation about parameters and formats.
Code: 132015 400 Bad Request

Template is Paused

Details: Template is paused due to low quality so it cannot be sent in a template message.
💡 Possible Reasons & Solutions
Edit the template to improve its quality and try again once it is approved.
Code: 132016 400 Bad Request

Template is Disabled

Details: Template has been paused too many times due to low quality and is now permanently disabled.
💡 Possible Reasons & Solutions
Create a new template with different content.
Code: 132068 400 Bad Request

Flow is blocked

Details: Flow is in blocked state.
💡 Possible Reasons & Solutions
Correct the Flow.
Code: 132069 400 Bad Request

Flow is throttled

Details: Flow is in throttled state and 10 messages using this flow were already sent in the last hour.
💡 Possible Reasons & Solutions
Correct the Flow and wait before sending more messages.
Code: 133000 500 Internal Server Error

Incomplete Deregistration

Details: A previous deregistration attempt failed.
💡 Possible Reasons & Solutions
Deregister the number again before registering.
Code: 133004 503 Service Unavailable

Server Temporarily Unavailable

Details: Server is temporarily unavailable.
💡 Possible Reasons & Solutions
Check the WhatsApp Business Platform Status page to see API status information and check the response details value before trying again.
Code: 133005 400 Bad Request

Two step verification PIN Mismatch

Details: Two-step verification PIN incorrect.
💡 Possible Reasons & Solutions
  • 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 documentation
Code: 133006 400 Bad Request

Phone number re-verification needed

Details: Phone number needs to be verified before registering.
💡 Possible Reasons & Solutions
Verify and register the phone number.
Code: 133008 400 Bad Request

Too Many two step verification PIN Guesses

Details: Too many two-step verification PIN guesses for this phone number.
💡 Possible Reasons & Solutions
Try again after the amount of time specified in the details response value.
Code: 133009 400 Bad Request

Two step verification PIN Guessed Too Fast

Details: Two-step verification PIN was entered too quickly.
💡 Possible Reasons & Solutions
Check the details response value before trying again.
Code: 133010 400 Bad Request

Phone number Not Registered

Details: Phone number not registered on the WhatsApp Business Platform.
💡 Possible Reasons & Solutions
Register the phone number before trying again.
Code: 133015 400 Bad Request

Please wait before registering this phone number

Details: The phone number you are attempting to register was recently deleted, and deletion has not yet completed.
💡 Possible Reasons & Solutions
Wait 5 minutes before re-trying the request.
Code: 134011 400 Bad Request

WhatsApp Payments terms not accepted

Details: Message failed to send because WhatsApp Payments terms of service acceptance is pending for this WhatsApp Business Account.
💡 Possible Reasons & Solutions
Accept the WhatsApp Payments terms of service using the link provided in the error message before trying again.
Code: 135000 400 Bad Request

Generic user error

Details: Message failed to send because of an unknown error with your request parameters.
💡 Possible Reasons & Solutions
  • 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

Powered by Xi © 2025 | WhatsApp Business API Error Reference