Welcome to Verloop.io’s WhatsApp’s Error Code User Guide.

This help doc is designed to provide information about adhering to specific compliance policies associated with the Cloud API. If you are unfamiliar with handling Graph API error responses, consult the Graph API’s error handling documentation before proceeding with the Cloud API.

Error Handling Recommendations

It is advised to construct your application’s error-handling logic around the ‘code’ values and ‘details’ payload properties. These properties offer more insightful information about the underlying errors. Although code titles are included in the message value, relying on titles for error handling is discouraged as they will eventually be deprecated.

Webhook Reporting

Certain API errors are reported via webhook. Webhook reporting is gradually being extended to cover all API error responses in the coming months. If you are subscribed to the messages webhook field, you will automatically receive these additional reports. The following webhook objects may surface API errors:

Cloud API

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

On-Premises API: errors
Error Response Contents (Code)

{
  "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 Scenarios

code (Integer): Represents the error code. It is recommended to base your application’s error handling on these codes rather than subcodes or HTTP response status codes.

details (String): Provides an error description along with insights into the most likely reason for the error. It may include guidance on addressing the error, such as identifying an invalid parameter or specifying acceptable values.

error_subcode (Integer): Deprecated. Not included in v16.0+ responses. Previously used as a Graph API subcode. Since not all responses include a subcode, it’s advisable to build error-handling logic around code and details properties instead.

fbtrace_id (String): A trace ID that can be included when reaching out to Direct Support. This ID aids in debugging the error and resolving issues efficiently.

message (String): A combination of the error code and its title. For example: “(#130429) Rate limit hit.”

messaging_product (String): Specifies the messaging product. It will always be the string “WhatsApp” for Cloud API responses.

type (String): Indicates the type of error that occurred.

Throttling Errors

Code: 4
Description: API Too Many Calls
Possible Solutions:
Load the app in the App Dashboard and check the Application Rate Limit section to verify if the app has reached its rate limit.
If the limit is reached, consider trying again later or reducing the frequency or number of API queries made by the app.
HTTP Status Code: 400 (Bad Request)

Code: 80007
Description: Rate limit issues
Possible Solutions: Refer to WhatsApp Business Account Rate Limits for more details.
To address the issue, try again later or decrease the frequency and volume of API queries made by the app.
HTTP Status Code: 400 (Bad Request)

Code: 130429
Description: Rate limit hit
Possible Solutions: Cloud API message throughput has been reached.
Review the Throughput documentation.
Consider trying again later or reducing the frequency of messages sent by the app.
HTTP Status Code: 400 (Bad Request)

Code: 131048
Description: Spam rate limit hit
Possible Solutions:
Message failed to send due to restrictions on the number of messages sent from a particular phone number.
Check the Quality status in the WhatsApp Manager and refer to the Quality-Based Rate Limits documentation.
HTTP Status Code: 400 (Bad Request)

Code: 131056
Description: (Business Account, Consumer Account) pair rate limit hit
Possible Solutions:
Too many messages sent from the sender's phone number to the same recipient's phone number in a short period.
Wait and retry the operation. Sending messages to a different phone number is still possible without waiting.
HTTP Status Code: 400 (Bad Request)

Code: 133016
Description: Account register deregister rate limit exceeded
Possible Solutions: Registration or Deregistration failed due to excessive attempts for this phone number in a short period.
Retry after one week. Refer to Registration Limitations for more information.
HTTP Status Code: 400 (Bad Request)

Integrity Errors

Code: 368
Description: Temporarily blocked for policy violations
Possible Solutions: The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy.
Refer to the Policy Enforcement document for information on policy violations and resolution steps.
HTTP Status Code: 403 (Forbidden)

Code: 131031
Description: The account has been locked
Possible Solutions: The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy or due to data verification issues.
Refer to the Policy Enforcement document for details on policy violations and resolution steps.
HTTP Status Code: 403 (Forbidden)

Other Errors

Code: 1
Description: API Unknown
Possible Solutions: Check the WhatsApp Business Platform Status page for API status information.
If there are no server outages, examine the endpoint reference to ensure correct request formatting and adherence to endpoint requirements.
HTTP Status Code: 400 (Bad Request)

Code: 2
Description: API Service
Possible Solutions: Verify the WhatsApp Business Platform Status page for API status information before retrying.
Temporary downtime or overloads may be causing the issue.
HTTP Status Code: 503 (Service Unavailable)

Code: 33
Description: Parameter value is not valid
Possible Solutions: The business phone number might have been deleted.
Ensure the correctness of the business phone number.
HTTP Status Code: 400 (Bad Request)

Code: 100
Description: Invalid parameter
Possible Solutions: Review the endpoint's reference to identify unsupported or misspelled parameters.
For business public key settings, ensure a valid 2048-bit RSA public key in PEM format.
Avoid mismatches between the registered phone number ID and previously stored IDs.
HTTP Status Code: 400 (Bad Request)

Code: 130472
Description: The user's number is part of an experiment
Possible Solutions:
The message was not sent as part of an experiment.
Refer to the Marketing Message Experiment.
HTTP Status Code: 400 (Bad Request)

Code: 131000
Description: Something went wrong
Possible Solutions:
Failure in setting a business public key, including calculation errors, GraphQL endpoint calls, or GraphQL endpoint errors.
Retry, and if the issue persists, open a Direct Support ticket.
HTTP Status Code: 500 (Internal Server Error)

Code: 131005
Description: Access denied
Possible Solutions:
Permissions not granted or removed.
Use the access token debugger to verify app permissions. Refer to Troubleshooting.
HTTP Status Code: 403 (Forbidden)

Code: 131008
Description: Required parameter is missing
Possible Solutions:
Identify and provide missing required parameters according to the endpoint's reference.
HTTP Status Code: 400 (Bad Request)

Code: 131009
Description: Parameter value is not valid
Possible Solutions:
Identify and correct invalid parameter values by referring to the endpoint's reference.
Follow Phone Numbers guidelines for adding a phone number.
HTTP Status Code: 400 (Bad Request)

Code: 131016
Description: Service unavailable
Possible Solutions: Check the WhatsApp Business Platform Status page for API status information before retrying.
HTTP Status Code: 500 (Internal Server Error)

Code: 131021
Description: Recipient cannot be sender
Possible Solutions: Send messages to a different phone number if the sender and recipient phone numbers are the same.
HTTP Status Code: 400 (Bad Request)

Code: 131026
Description: Message Undeliverable
Possible Solutions:
Confirm recipient's phone number is a WhatsApp number and complies with the new Terms of Service.
Ensure the recipient uses a WhatsApp version as specified.
HTTP Status Code: 400 (Bad Request)

Code: 131042
Description: Business eligibility payment issue
Possible Solutions:
Message failed due to payment method errors. Refer to About Billing For Your WhatsApp Business Account.
Resolve common problems affecting payment method functionality.
HTTP Status Code: 400 (Bad Request)

Code: 131045
Description: Incorrect certificate
Possible Solutions:
The message failed due to a phone number registration error.
Register the phone number before retrying.
HTTP Status Code: 500 (Internal Server Error)

Code: 131047
Description: Re-engagement message
Possible Solutions:
More than 24 hours have passed since the recipient last replied.
Send a business-initiated message using a message template instead.
HTTP Status Code: 400 (Bad Request)

Code: 131051
Description: Unsupported message type
Possible Solutions:
Ensure message type is supported. Refer to Messages for supported types.
Retry with a supported message type.
HTTP Status Code: 400 (Bad Request)

Code: 131052
Description: Media download error
Possible Solutions:
Unable to download media sent by the user.
Check error details for more information and ensure the media is supported.
HTTP Status Code: 400 (Bad Request)

Code: 131053
Description: Media upload error
Possible Solutions:
Unable to upload media used in the message.
Check error details for more information and ensure the media is supported.
Refer to Media HTTP Caching for reliable media performance.
HTTP Status Code: 400 (Bad Request)

Code: 131057
Description: Account in maintenance mode
Possible Solutions:
The WhatsApp Business Account is in maintenance mode, potentially undergoing a throughput upgrade.
HTTP Status Code: 500 (Bad Request)

Code: 132000
Description: Template Param Count Mismatch
Possible Solutions:
Ensure the number of variable parameter values matches those defined in the template.
Refer to Message Template Guidelines.
HTTP Status Code: 400 (Bad Request)

Code: 132001
Description: Template does not exist
Possible Solutions:
Ensure the template is approved, exists in the specified language, and follows message template guidelines.
HTTP Status Code: 404 (Not Found)

Code: 132005
Description: Template Hydrated Text Too Long
Possible Solutions:
Check WhatsApp Manager for translated templates and adhere to Quality Rating and Template Status.
HTTP Status Code: 400 (Bad Request)

Code: 132007
Description: Template Format Character Policy Violated
Possible Solutions:
Address template content violating WhatsApp policies. Refer to Rejection Reasons.
HTTP Status Code: 400 (Bad Request)

Code: 132012
Description: Template Parameter Format Mismatch
Possible Solutions:
Correctly format variable parameter values according to the template. Refer to Message Template Guidelines.
HTTP Status Code: 400 (Bad Request)

Code: 132015
Description: Template is Paused
Possible Solutions:
Improve template quality for approval if paused. Create a new template with different content if permanently disabled.
HTTP Status Code: 400 (Bad Request)

Code: 132016
Description: Template is Disabled
Possible Solutions:
Create a new template with different content as the current template is permanently disabled.
HTTP Status Code: 400 (Bad Request)

Code: 132068
Description: Flow is blocked
Possible Solutions:
Correct the Flow to resolve the blocked state.
HTTP Status Code: 400 (Bad Request)

Code: 132069
Description: Flow is throttled
Possible Solutions:
Correct the Flow to address throttling, especially if 10 messages have been sent in the last hour.
HTTP Status Code: 400 (Bad Request)

Code: 133000
Description: Incomplete Deregistration
Possible Solutions:
Retry deregistration as a previous attempt failed.
HTTP Status Code: 500 (Internal Server Error)

Code: 133004
Description: Server Temporarily Unavailable
Possible Solutions:
Check the WhatsApp Business Platform Status page for API status information and response details before retrying.
HTTP Status Code: 503 (Service Unavailable)

Code: 133005
Description: Two-step verification PIN Mismatch
Possible Solutions:
Verify the correct two-step verification PIN is included in the request. Reset if necessary.
Follow the steps to reset the two-step verification PIN as specified.
HTTP Status Code: 400 (Bad Request)

Code: 133006
Description: Phone number re-verification needed
Possible Solutions:
Verify the phone number before attempting registration.
HTTP Status Code: 400 (Bad Request)

Code: 133008
Description: Too Many Two-step Verification PIN Guesses
Possible Solutions:
Wait for the specified time period mentioned in the detailed response value before trying again.
HTTP Status Code: 400 (Bad Request)

Code: 133009
Description: Two-step verification PIN Guessed Too Fast
Possible Solutions:
Check the detailed response value before attempting again and avoid rapid attempts.
HTTP Status Code: 400 (Bad Request)

Code: 133010
Description: Phone number Not Registered
Possible Solutions:
Register the phone number before retrying.
HTTP Status Code: 400 (Bad Request)

Code: 133015
Description: Please wait a few minutes before attempting to register this phone number
Possible Solutions:
Wait for 5 minutes before re-trying the request, especially if the phone number was recently deleted.
HTTP Status Code: 400 (Bad Request)

Code: 135000
Description: Generic user error
Possible Solutions:
Check the endpoint's reference to ensure correct syntax in the request parameters.
Contact customer support if the error code persists.
HTTP Status Code: 400 (Bad Request)

If you have any further questions, feel free to reach out to us at support@verloop.io