WhatsApp error code

Monitor both the API response and whatsapp.message.updated webhooks. A message can fail when YCloud validates your request, when it submits the message to WhatsApp, or after WhatsApp accepts the message for delivery. Use the returned code and details to identify the cause before retrying.

Find the error code

Where the failure occurs	Where to read the error
YCloud rejects the request before submitting it to WhatsApp	Read `error.code`, `error.message`, and `error.target` in the API response. No upstream `whatsappApiError` is available.
WhatsApp rejects a synchronous submission through `POST /v2/whatsapp/messages/sendDirectly`	Read the YCloud error fields alongside `error.whatsappApiError`, when present. Its `code` identifies the upstream WhatsApp error.
A queued message fails during submission through `POST /v2/whatsapp/messages`	Read `whatsappMessage.status`, `whatsappMessage.errorCode`, and `whatsappMessage.errorMessage` in the `whatsapp.message.updated` webhook. Inspect `whatsappMessage.whatsappApiError` when present.
WhatsApp accepts the message but later fails to deliver it	Read `whatsappMessage.errorCode` and `whatsappMessage.errorMessage` in a `whatsapp.message.updated` webhook with `whatsappMessage.status: "failed"`. Do not require a `whatsappApiError` object to process the failure.
An inbound message contains an unsupported-content or media error	In the `whatsapp.inbound_message.received` webhook, inspect `whatsappInboundMessage.errors[]` when present. Each entry can include `code`, `message`, and `error_data.details`.

The queued endpoint returns before the message is submitted to WhatsApp, so its initial response cannot report a later submission failure. The synchronous endpoint reports the submission result, but the message can still fail afterward. An accepted request does not confirm delivery; monitor webhooks for both endpoints.

Read the code and details

Keep the YCloud request error and the upstream WhatsApp error separate. For example, a synchronous response can contain error.code: "TOO_MANY_REQUESTS" and error.whatsappApiError.code: "131056". The first describes the API response; the second identifies the sender–recipient rate limit. For a failed-message webhook, whatsappMessage.errorCode can contain either a YCloud code such as BALANCE_INSUFFICIENT or a WhatsApp code such as 131048. Preserve it as a string. When whatsappApiError is available, inspect its code and error_data for the specific cause. For message API errors, error_data can contain a details property; for template API errors, it can instead be a string. Match codes rather than error titles or message text, which can change. The numeric codes below describe upstream WhatsApp failures. For YCloud codes such as UNAUTHORIZED, PARAM_INVALID, or BALANCE_INSUFFICIENT, see Handle errors. See Send a WhatsApp message for the sending endpoints and Configure webhooks to receive message status updates.

Sending limits and quality restrictions

Code	Meaning	What to do
`80007`	The WhatsApp Business Account has reached its API call limit.	Reduce requests for the affected WABA and retry later with backoff.
`130429`	Message throughput has been exceeded.	Reduce the sending rate for the affected business phone number and spread sends over time.
`131048`	Sending is restricted because of spam or quality signals.	Pause affected sends. Review phone-number quality, audience consent, and recent negative feedback before resuming.
`131056`	Too many messages were sent from one business number to the same recipient in a short period.	Wait before retrying that sender–recipient pair. This specific limit does not prevent sends to other recipients.
`131064`	Template classification violations have caused a messaging restriction.	Review template categories and correct misclassified content. The restriction applies to template and Direct Send messages and is lifted after the enforcement period.

See Quality and delivery controls for quality and recipient-level restrictions.

Recipient and delivery errors

Code	Meaning	What to do
`130403`	Your business has blocked the recipient on WhatsApp.	Do not retry while the block remains. Review the block before deciding whether communication should resume.
`130472`	WhatsApp withheld the message as part of a platform experiment.	Do not repeatedly resend the same message. Use another agreed communication channel if the information is time-sensitive.
`131021`	The sender and recipient phone numbers are the same.	Send to a different recipient number.
`131026`	The message could not be delivered. Possible causes include a number that is not on WhatsApp, unaccepted WhatsApp terms, or an outdated client.	Through another agreed channel, ask the recipient to confirm that they can message your business, accept the current WhatsApp terms, and update WhatsApp. The code alone does not identify one definitive cause.
`131047`	The 24-hour customer service window has expired.	Send an appropriate approved template, or wait for a new message from the customer before sending a free-form reply.
`131049`	WhatsApp withheld the message to protect recipient engagement.	Avoid immediate retries. If you suspect a recipient marketing limit, wait at least 24 hours before considering another send. First check consent and relevance; waiting does not guarantee delivery.
`131050`	The recipient stopped marketing messages from your business on WhatsApp.	Stop marketing sends to this recipient. Do not retry the failed marketing message.

Template and Flow message errors

Check the exact template name, language, status, and component definitions in YCloud before retrying.

Code	Meaning	What to do
`132000`	The number of supplied template parameters does not match the template.	Supply the required number of values for each component.
`132001`	The template is missing in the requested language or is not approved.	Check the name, language code, WABA, and approval status.
`132005`	The template text exceeds the allowed length.	Review the template and supplied text values against the applicable length limits.
`132007`	Template content violates a WhatsApp policy.	Review the reported violation and correct the content before resubmitting.
`132012`	Template parameter formats do not match the definition.	Check each component and parameter type, including media headers and buttons.
`132015`	The template is paused because of low quality.	Stop sends using it. Improve its content and resume only when the template is approved and usable.
`132016`	The template is permanently disabled after repeated quality pauses.	Create a replacement with different content and address the quality issue before sending.
`132068`	The Flow used in the message is blocked.	Check the Flow’s status and resolve the reported issue before using it again.
`132069`	The Flow is throttled and has reached its limited sending allowance.	Review the Flow’s health and recent sends. Resolve the issue and wait before retrying.

See Manage WhatsApp templates and Manage WhatsApp Flows.

Message parameters and media

Code	Meaning	What to do
`100`	The request contains an unsupported or invalid parameter.	Read the returned details and correct the corresponding field using the YCloud endpoint reference.
`131008`	A required parameter is missing.	Add the field or component identified in the error.
`131009`	A parameter value is invalid.	Correct the value, format, or length identified in the error details.
`131051`	The message type is unsupported.	For outbound sends, use a supported YCloud message type. For inbound messages, handle the unsupported event without assuming ordinary message content is available.
`131052`	WhatsApp could not download media sent by the user.	Inspect the inbound error details. Ask the user to share the file through another agreed channel if needed.
`131053`	Media used in the outbound message could not be uploaded.	Check the actual file format, MIME type, size, and accessibility. Correct the file or URL before retrying.
`135000`	WhatsApp reported an unspecified request-parameter error.	Check the request against the YCloud API schema and preserve the returned details.

See Send a WhatsApp message and Upload WhatsApp media.

Account, phone number, and billing

Code	Meaning	What to do
`368`, `131031`	The WABA is restricted or locked. For `131031`, account verification data can also be involved.	Check the account status and the exact error details.
`130497`	The WABA cannot message users in certain countries.	Check the destination and restrictions for your business category. Do not retry an unsupported destination unchanged.
`131042`	WhatsApp reported a payment or account billing issue.	Check the WABA’s billing connection. This is distinct from YCloud’s `BALANCE_INSUFFICIENT`; topping up alone may not resolve it.
`131045`, `133010`	The business phone number has a registration problem or is not registered.	Check the number’s connection and registration status in YCloud.
`131057`	The account is temporarily in maintenance mode.	Wait for maintenance to finish and retry with backoff.

Marketing message errors

These errors can occur when YCloud submits a message through Meta’s Marketing Messages API. Use the returned details to distinguish template, synchronization, and routing issues.

Code	Meaning	What to do
`131055`, `134100`	The upstream marketing route accepts only marketing templates.	Confirm that the intended message uses a `MARKETING` template. Utility and authentication templates require a different sending route.
`131063`	Marketing templates are disabled on the account’s Cloud API route.	Check the marketing sending route and account configuration.
`134101`	The marketing template is still synchronizing.	Wait 10 minutes before retrying the newly created template.
`134102`	The template is unavailable because synchronization or account eligibility is incomplete.	Check the account’s eligibility and whether template synchronization has completed.
`132018`	Template parameter validation failed.	Correct the parameters identified in the error and resend only after validation succeeds.

For this route, 100 can mean that the message must be a template, and 131009 can indicate invalid parameters or incomplete template synchronization. Use the returned details to distinguish these causes. For incomplete synchronization, wait 10 minutes before retrying.

Temporary service errors

Code	Meaning	What to do
`1`	An invalid request or an upstream server error.	Check the request first. If it is valid, investigate a temporary service issue.
`2`, `131016`	An upstream service is temporarily unavailable or overloaded.	Check WhatsApp Business Platform status and retry temporary failures with bounded backoff.
`131000`	An unspecified WhatsApp failure.	Check service status and the returned details. Use bounded retries only when appropriate.

Retry and escalate

Correct invalid parameters, template status, account restrictions, and media problems before retrying.
Respect recipient opt-outs and blocks. Do not retry those failures automatically.
Use exponential backoff, jitter, and a maximum attempt count for temporary failures. Apply any waiting period specified above or in the response.
Before resending after a timeout or an ambiguous response, reconcile the message status to avoid duplicates. externalId is a correlation field; do not assume it deduplicates sends.

If an error persists after the checks above, or you need help with account billing, eligibility, or sending-route configuration, contact YCloud support. Include the failure time and timezone, endpoint, exact error code and details, YCloud requestId, message id, and wamid or fbtrace_id when available. Remove API keys and unnecessary personal data.

Getting Started

Guides

Endpoints

Webhooks

Find the error code

Read the code and details

Sending limits and quality restrictions

Recipient and delivery errors

Template and Flow message errors

Message parameters and media

Account, phone number, and billing

Marketing message errors

Temporary service errors

Retry and escalate

​Find the error code

​Read the code and details

​Sending limits and quality restrictions

​Recipient and delivery errors

​Template and Flow message errors

​Message parameters and media

​Account, phone number, and billing

​Marketing message errors

​Temporary service errors

​Retry and escalate

Find the error code

Read the code and details

Sending limits and quality restrictions

Recipient and delivery errors

Template and Flow message errors

Message parameters and media

Account, phone number, and billing

Marketing message errors

Temporary service errors

Retry and escalate