> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp error code

> Look up WhatsApp messaging error codes and resolve failed messages sent through YCloud.

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](/en/api-reference/guides/api-fundamentals/handle-errors).

See [Send a WhatsApp message](/en/api-reference/guides/whatsapp-platform/send-whatsapp-message) for the sending endpoints and [Configure webhooks](/en/api-reference/guides/api-fundamentals/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](/en/documentation/whatsapp-business-platform/pricing-limits-and-quality/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](/en/api-reference/guides/whatsapp-platform/manage-whatsapp-templates) and [Manage WhatsApp Flows](/en/api-reference/guides/whatsapp-platform/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](/en/api-reference/guides/whatsapp-platform/send-whatsapp-message) and [Upload WhatsApp media](/en/api-reference/guides/whatsapp-platform/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](https://metastatus.com/whatsapp-business-api) 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](https://www.ycloud.com/console/#/app/getStarted). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.