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

# WhatsApp errors

> Find a WhatsApp error by its cause, such as account access, senders, recipients, or templates, and see how to fix it.

Each WhatsApp error has a page that says what happened, whether to try again, and how to fix it. If you have the error code, search for it, or open the link that comes with the error.

## Errors by cause

### Account and access

| Error | What happened |
| - | - |
| [Authentication required](https://docs.wavix.com/errors/authentication-required) | The request doesn't include a valid API key. |
| [Access denied](https://docs.wavix.com/errors/access-denied) | The API key is valid but isn't allowed to make this request. |
| [WhatsApp not available](https://docs.wavix.com/errors/whatsapp-not-available) | WhatsApp isn't available for the account that owns the API key. |
| [Channel not enabled](https://docs.wavix.com/errors/channel-not-enabled) | The account has WhatsApp access, but the WhatsApp channel isn't set up yet. |
| [Capability missing](https://docs.wavix.com/errors/capability-missing) | The WhatsApp feature the request needs isn't enabled for the account. |
| [Payment required](https://docs.wavix.com/errors/payment-required) | The account balance is too low to send the message. |

### Senders and WhatsApp Business Accounts

| Error | What happened |
| - | - |
| [Sender not found](https://docs.wavix.com/errors/sender-not-found) | The WhatsApp sender in the request isn't on your account or isn't connected. |
| [WhatsApp Business Account not linked](https://docs.wavix.com/errors/waba-not-linked) | The WhatsApp Business Account in the request isn't linked to your Wavix account. |
| [Sender unavailable](https://docs.wavix.com/errors/sender-unavailable) | Not delivered: the sender can't send messages. |
| [Sender limit reached](https://docs.wavix.com/errors/sender-limit-reached) | Not delivered: the sender reached its messaging limit. |
| [Sender rate limited](https://docs.wavix.com/errors/sender-rate-limited) | Not delivered: WhatsApp slowed down the sender. |

### Recipients

| Error | What happened |
| - | - |
| [Recipient isn't on WhatsApp](https://docs.wavix.com/errors/recipient-not-on-whatsapp) | Not delivered: the recipient's number isn't on WhatsApp. |
| [Recipient opted out](https://docs.wavix.com/errors/recipient-opted-out) | Not delivered: the recipient turned off marketing messages, or blocked your sender or template. |
| [Marketing limit reached](https://docs.wavix.com/errors/marketing-limit-reached) | Not delivered: the recipient already got as many marketing messages as WhatsApp allows. |
| [Service window closed](https://docs.wavix.com/errors/service-window-closed) | A free-form WhatsApp message can't be sent because the 24-hour customer service window is closed. |

### Templates

| Error | What happened |
| - | - |
| [Template not found](https://docs.wavix.com/errors/template-not-found) | No message template with that ID exists on your account. |
| [Template already exists](https://docs.wavix.com/errors/template-already-exists) | A message template with this name and language already exists. |
| [Template invalid](https://docs.wavix.com/errors/template-invalid) | The message template can't be created as submitted. |
| [Template not approved](https://docs.wavix.com/errors/template-not-approved) | Not delivered: its template isn't approved or ready to send yet, or can't be sent from your sender. |
| [Template paused or disabled](https://docs.wavix.com/errors/template-paused-or-disabled) | Not delivered: Meta paused or disabled its template. |
| [Invalid template parameters](https://docs.wavix.com/errors/invalid-template-parameters) | Not delivered: its parameters don't match the template. |

### Webhooks

| Error | What happened |
| - | - |
| [Invalid webhook URL](https://docs.wavix.com/errors/invalid-webhook-url) | The webhook URL isn't a public https URL. |
| [Webhook already exists](https://docs.wavix.com/errors/webhook-already-exists) | The account already has a WhatsApp webhook for this group of events. |
| [Webhook not found](https://docs.wavix.com/errors/webhook-not-found) | No WhatsApp webhook with that ID exists on your account. |
| [Webhook URL unverified](https://docs.wavix.com/errors/webhook-url-unverified) | Wavix couldn't resolve the host of the webhook URL. |

### Requests

| Error | What happened |
| - | - |
| [Invalid request](https://docs.wavix.com/errors/invalid-request) | The request body or a parameter failed validation. |
| [Resource not found](https://docs.wavix.com/errors/resource-not-found) | The endpoint or the object in the request doesn't exist. |
| [Payload too large](https://docs.wavix.com/errors/payload-too-large) | The request body is larger than the API accepts. |

### Temporary and other errors

| Error | What happened |
| - | - |
| [Rate limited](https://docs.wavix.com/errors/rate-limited) | The account sent too many requests in a short time. |
| [Internal error](https://docs.wavix.com/errors/internal-error) | An unexpected error occurred on the Wavix platform. |
| [Service unavailable](https://docs.wavix.com/errors/service-unavailable) | The service is temporarily unavailable. |
| [Message expired](https://docs.wavix.com/errors/message-expired) | Not delivered: the message expired before it was delivered. |
| [Delivery failed](https://docs.wavix.com/errors/delivery-failed) | The WhatsApp message wasn't delivered, and the cause isn't one of the other delivery errors. |

## How delivery errors reach you

A request error comes back in the API response. For its format, see [Request errors](https://docs.wavix.com/api-reference/errors.md#request-errors).

A delivery error comes later: the API accepted the message, and it wasn't delivered. Wavix retries temporary failures itself, so you get a delivery error only after Wavix stops retrying. Wavix sends a `whatsapp.message.failed` event to your webhook for the `messages` group, and the event's `data.error` says why. [Retrieve a WhatsApp message](https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-message.md) and [List WhatsApp messages](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-messages.md) return the same object in the `error` field.

```json theme={null}
{
  "id": "evt_7c9e1a3b5d7f4c2e8a0b2d4f6a8c0e1b",
  "type": "whatsapp.message.failed",
  "timestamp": "2026-10-21T08:32:40.000000Z",
  "data": {
    "message_uuid": "3a525ca2-6909-4c72-9399-905adf7f3a74",
    "from": "+14155550100",
    "to": "+14155550123",
    "status": "undelivered",
    "error": {
      "code": "RECIPIENT_NOT_ON_WHATSAPP",
      "subcode": "BLOCKED_BY_OPERATOR",
      "message": "This number can't receive WhatsApp messages from businesses.",
      "action": "do_not_resend",
      "docs_url": "https://docs.wavix.com/errors/recipient-not-on-whatsapp"
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `code` | string | Stable, machine-readable code of the error, in the same format as `error_code` in request errors. |
| `subcode` | string or `null` | Finer cause within `code`, or `null` when Wavix has no finer cause. The page for each code lists its subcodes. |
| `message` | string | Short explanation in plain language, from the most specific of `subcode` and `code`. Its text can change. |
| `action` | string | What to do about the message: `resend_later`, `fix_and_resend`, `do_not_resend`, or `contact_support`. |
| `docs_url` | string | URL of the page that explains the error and how to fix it. |

To decide what to do about the message, use `action`. Every delivery error has it, including codes and subcodes that Wavix adds later. To tell causes apart, use `code` and `subcode`, not `message`. Wavix can add codes and subcodes, so handle a code you don't recognize as `DELIVERY_FAILED`, and a subcode you don't recognize by `code` alone.

To send a message again, send a new request with a new `idempotency_key`. A request with the same key returns the original message and sends nothing.

To receive these events, [create a webhook](https://docs.wavix.com/api-reference/whatsapp/create-a-whatsapp-webhook.md) for the `messages` group. To read events you missed, use [List WhatsApp events](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-events.md).

## Get help

If an error persists, contact [support@wavix.com](mailto:support@wavix.com). For a request error, include the `instance` value from the response. For a delivery error, include the `message_uuid` from the event. The Wavix team uses them to find your request or message.


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