Error Code
Webhook Error Codes for WhatsApp Message Delivery
This section provides a comprehensive guide to the error codes encountered during the WhatsApp message delivery process via webhooks. Understanding these codes is crucial for diagnosing issues and implementing effective solutions to ensure the seamless delivery of messages.
Authorization Errors
Description: These errors occur when the app, operator, or account lacks required permissions to perform an action or access a resource.
111001
Application does not have permission
The application does not have the permission required to perform this action.
Permission is either not granted or has been removed.
111002
API Permission
The API permission for the requested service is not granted.
Permission is either not granted or has been removed.
111003
Not part of the provider network
The requested service is not allowed.
Please check your permissions or contact support.
111004
Operator not allowed
The operator is not authorized to perform this action.
Please contact support.
111005
Service not allowed
The requested service is not allowed.
Please check your permissions or contact support.
111006
Unsupported post request
The request method or endpoint is not supported.
—
111007
API access disrupted
API access has been disrupted.
Please visit the App Dashboard and complete the Data Use Checkup to restore access.
111008
Forbidden user
User does not have access to the required billing channel.
Please contact support.
111009
Invalid token
The requested service is not allowed due to invalid or expired token.
Please check your permissions or contact support.
Business Account Errors
Description: Errors related to the WhatsApp Business Account’s operational status, active session windows, or Meta-imposed delivery limits.
Error Code
Reason
Description
Recommended Action
131031
Account has been locked
Your WhatsApp Business Account is restricted and cannot send messages.
Contact OCA Helpdesk for further information regarding account restrictions.
131047
Re-engagement message
Message failed because more than 24 hours have passed since the customer last replied.
Session ended after 24 hours. Send another broadcast using a template.
131049
Maintain healthy ecosystem engagement
Message was not delivered to maintain a healthy engagement ecosystem.
WhatsApp limits each number to 2–3 marketing messages every 24 hours to prevent spam. Try sending another broadcast in a few hours. Read this article to learn more.
131050
User has stopped receipt of marketing messages
The recipient has opted out of receiving marketing messages from your business.
Do not retry sending messages to this user as they will not be received.
131057
Business Account in maintenance mode
The business account is currently in maintenance mode.
The business account is currently in maintenance mode and cannot process requests at this time.
Network Errors
Description: Errors triggered by network instability or issues in communication between your server and the WhatsApp API.
Error Code
Reason
Description
Recommended Action
113001
cURL error 28
Network connection timed out or was unstable.
Network unstable. Restart connection and try creating new broadcast.
113003
cURL error 35
SSL connection error or internal communication failure.
Try creating another broadcast or contact OCA Helpdesk.
113004
cURL error 7
Failed to connect to host.
Try creating another broadcast or contact OCA Helpdesk.
Other Errors
Description: These errors are general system or message delivery issues that are not specific to a particular category (e.g. internal server errors, unknown errors, or message timeout conditions).
Error Code
Reason
Description
Recommended Action
114001
Invalid response code (502)
The server returned a 502 Bad Gateway error, indicating that it received an invalid response from an upstream server.
Please try again later or contact support for further assistance.
131008
Required parameter is missing
One or more required parameters were not included in the request.
The request is missing a required parameter.
114002
An unexpected error has occurred
An unexpected error occurred while processing the request.
Please try again or contact support.
114003
An unknown error occurred
An unknown error occurred.
Please try again later or contact support.
114004
Request for URL failed
The request could not be completed.
Please try again later or contact support if the issue persists.
114005
read ECONNRESET
The connection was reset by the server.
Try creating another broadcast or contact OCA Helpdesk.
114006
Message failed to send because it was pending for too long
The message remained pending too long before being processed by WhatsApp servers.
Message failed to send because it was pending for too long. Try sending the message again. If the issue persists, check your server connection or message queue.
131053
Media upload error
Media upload failed due to unsupported file type or upload problem.
Check the media file for errors or unsupported formats. Verify MIME type with file -I <filename> and ensure it is included in WhatsApp’s Supported Media Types list.
75
There was an internal server error while processing your request. Please try again later
An unexpected error occurred while processing the request.
Please try again or contact support.
Quota Errors
Description: Triggered when the available WhatsApp message quota for a specific category has been used up or the billing account has expired.
Error Code
Reason
Description
Recommended Action
115001–115005
Insufficient Quota
Insufficient quota for sending message
Lakukan top up kuota sesuai kebutuhan broadcast.
115006
Account expired
The billing account has expired.
Your billing account has expired. Please renew it to continue using the service.
Rate Limit Errors
Description: These errors occur when message sending or API request limits are exceeded for a specific WhatsApp number, application, or broadcast session.
Error Code
Reason
Description
Recommended Action
130429
Rate limit hit
Cloud API message throughput limit has been reached.
Contact OCA Helpdesk for further assistance.
131048
Spam rate limit hit
Sending rate restricted due to previous spam or blocked messages.
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.
131056
Daily rate limit exceeded
Daily broadcast sending limit exceeded.
WhatsApp stopped broadcast sending because your OCA account sent too many broadcasts in a short time. Adjust your broadcast schedule and ensure there are no duplicate numbers within your contact groups.
133016
Account register/deregister rate limit exceeded
Too many registration or deregistration attempts in a short period.
Registration or Deregistration failed because there were too many attempts for this phone number in a short period of time.
116001
Application request limit reached
The app exceeded its request limit.
Try again later.
116002
Invalid response code (429)
Server received too many requests in a short time.
Please try again later or reduce the frequency of your requests.
116003
Throttled
Requests were temporarily throttled by the server.
Try again with fewer broadcasts to avoid limits.
Recipient Errors
Description: These errors are caused by invalid recipient phone numbers, unsupported devices or WhatsApp versions, or user participation in marketing-related experiments.
Error Code
Reason
Description
Recommended Action
117001
Unsupported country code
The country code is not supported in OCA’s system.
Verify that the recipient’s phone number uses a valid and supported country code.
117002
Unregistered WhatsApp number
The recipient number is not registered on WhatsApp.
Update contact information for this recipient.
117003
Contact doesn’t exist
The specified contact could not be found.
Verify recipient number.
117004
Invalid MSISDN
Invalid phone number format or incorrect MSISDN.
Update contact information for this recipient.
117005
Message expired
The message has expired and can no longer be delivered.
Failed to send within time limit. Contact OCA Helpdesk for assistance.
117006
Unsupported WhatsApp version
The recipient’s WhatsApp version does not support this message type.
Message failed to send because the receiver is on a version of WhatsApp that does not support this message.
117007
Not suitable device
The recipient’s device is not supported for this message.
The device is not suitable for this operation. Please ensure the device meets the required specifications or try a different device.
130472
User’s number is part of an experiment
The user is part of WhatsApp’s marketing message experiment and cannot receive marketing messages.
Message will not be sent or billed. Cannot be resent. Contact the user through another channel and ask them to message your business so you can resend within an open customer service window.
Subscription Errors
Description: Errors related to expired or invalid billing accounts that prevent further message delivery.
Error Code
Reason
Description
Recommended Action
115006
Account Expired
Your billing account has expired.
Your billing account has expired. Please renew it to continue using the service.
System Errors
Description: Errors caused by internal WhatsApp system issues, overload, or downtime affecting broadcast or message processing.
Error Code
Reason
Description
Recommended Action
118001
System Overload
WhatsApp system temporarily overloaded.
Temporary due to downtime or system overload. Please contact support.
118002
System Error
Provider failed to process broadcast.
Quota will be refunded within a maximum of 31 days.
118003
System Error
Internal error occurred.
Please try again or contact support.
118004
System Error
Generic internal failure.
—
Template Errors
Description: Errors due to issues with message templates, such as invalid parameters, missing templates, or templates paused by Meta.
Error Code
Reason
Description
Recommended Action
132000
Invalid Template Parameters or Variables
The template includes invalid or incorrectly formatted parameters.
Check the endpoint reference to determine which parameters are required.
132001
Template does not exist
The template does not exist or is not approved for the selected language.
The template does not exist in the specified language or has not been approved. Contact OCA Helpdesk for assistance checking your template category.
132005
Message Exceeds Character Limit
Template body text exceeds the 1024-character limit.
Ensure the number of characters in the Body Message does not exceed 1024, including variables.
132012
Template Parameter Format Mismatch
The template structure or variables do not match expected format.
Check the template and ensure all message elements match the required format.
132015
Template Paused
The template has been paused due to low quality and cannot be used.
Edit the template or create a broadcast with a new one.
119001
Template Category Not Found
The template category does not exist or is invalid.
The category was not found. Contact OCA Helpdesk for assistance verifying your template category.
119002
Invalid Message Format
The body of the template is invalid.
The request contains unsupported or misspelled parameters. Double-check your template format.
119003
Template Not Found
The specified template does not exist.
Template not found. Make sure the template has been approved.
119004
Number of Parameters Does Not Match Expected Count
Parameter count mismatch between template and payload.
A parameter value is invalid. Please check your inputs and try again.
Validation Errors
Description: Validation issues caused by incomplete data, incorrect parameter values, invalid sender/operator information, or unsupported request types.
Error Code
Reason
Description
Recommended Action
131000
Something went wrong
Message failed to send due to an unknown validation error.
—
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 check how to add a phone number to a WhatsApp Business Account.
121001
Incomplete Parameter
The request is missing one or more required parameters.
A parameter value is invalid. Please check your inputs and try again.
121002
Sender not found
The specified sender could not be found or verified.
The specified sender could not be found. Please verify the sender’s details and try again.
121003
Operator not found
The specified operator does not exist in the system.
Try creating another broadcast or contact OCA Helpdesk.
121004
Parameter value is not valid
A parameter value is invalid.
A parameter value is invalid. Please check your inputs and try again.
121005
Resource type is invalid
The specified resource type is unsupported.
The specified resource type is invalid or unsupported.
121006
Unsupported request - method type: POST
Unsupported HTTP method used.
The requested operation is not supported. Check the method type and try again.
Last updated