# Meta WhatsApp Error Codes

> Meta's own WhatsApp error codes, where they appear in Avox, and how each one maps to an Avox API error code.

Source: https://docs.theavoxai.com/meta-error-codes

These are **Meta's own** error numbers, returned by WhatsApp's Cloud API. They're separate from
Avox's own [AVX-XXXX error codes](https://docs.theavoxai.com/error-codes) (shown in the dashboard) and from the
[Avox API error codes](https://docs.theavoxai.com/api/errors) (like `template_not_found`) your server branches on.

## Where you'll see them

| Where | What it looks like |
| --- | --- |
| An [Avox API](https://docs.theavoxai.com/avox-api) response | `error.meta_code` next to the Avox `error.code`, when WhatsApp refused the send. The same Avox code is on the request's row on the **Sent** tab of **API logs** (see [API logs](https://docs.theavoxai.com/connections/api-keys#api-logs)), linked to its explanation. |
| The [Logs](https://docs.theavoxai.com/logs) page | `statuses[].errors[].code` in a `failed` status (problems WhatsApp found after accepting a message), or inside an alert event. See [Delivery statuses and replies](https://docs.theavoxai.com/avox-api/webhooks). |
| The connection wizard | "Meta error" and a number, when Meta's signup popup reports an error. See [Embedded Signup](https://docs.theavoxai.com/whatsapp/embedded-signup). |
| [Health](https://docs.theavoxai.com/health) | **Check health now** lists issues Meta reports for the number, account, business or app, in Meta's words. |

> **Note**
>
> This page covers the codes you're most likely to meet. Meta's
> [developer documentation](https://developers.facebook.com/docs/whatsapp) is the complete,
> always-current reference - check there for any code not listed here.

## How Meta codes map to Avox API codes

When WhatsApp refuses a send made through the Avox API, Avox turns Meta's code into one stable
Avox code, so your code only has to handle a short list. Avox checks Meta's code first, then the
HTTP status Meta answered with:

| Meta code | Avox API code |
| --- | --- |
| `132001` | [`template_not_found`](https://docs.theavoxai.com/api/errors#template_not_found) |
| `132015`, `132016` | [`template_unavailable`](https://docs.theavoxai.com/api/errors#template_unavailable) |
| `132000`, `132005`, `132007`, `132012` | [`template_params_invalid`](https://docs.theavoxai.com/api/errors#template_params_invalid) |
| `131047` | [`outside_messaging_window`](https://docs.theavoxai.com/api/errors#outside_messaging_window) |
| `131021`, `131026`, `131030`, `131049`, `133010`, `137000` | [`recipient_unreachable`](https://docs.theavoxai.com/api/errors#recipient_unreachable) |
| `4`, `80007`, `130429`, `131048`, `131056` | [`meta_rate_limited`](https://docs.theavoxai.com/api/errors#meta_rate_limited) |
| `10`, `190`, `200`, `131005`, `133000` | [`connection_not_ready`](https://docs.theavoxai.com/api/errors#connection_not_ready) |
| No answer, or a server error from Meta | [`meta_unavailable`](https://docs.theavoxai.com/api/errors#meta_unavailable) |
| Any other `429` from Meta | [`meta_rate_limited`](https://docs.theavoxai.com/api/errors#meta_rate_limited) |
| Anything else | [`meta_rejected`](https://docs.theavoxai.com/api/errors#meta_rejected) |

## Meta's error shape

Every Meta Graph API error, WhatsApp included, uses the same envelope:

```json
{
  "error": {
    "message": "(#131047) Re-engagement message",
    "type": "OAuthException",
    "code": 131047,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number."
    },
    "fbtrace_id": "AbCdEf123456"
  }
}
```

`code` is the number to look up below. The Avox API passes only that number on, as `meta_code` -
Meta's wording stays out of your responses. An Avox API error looks like this:

```json
{
  "ok": false,
  "error": {
    "code": "outside_messaging_window",
    "message": "It's been more than 24 hours since this person last messaged you. Send an approved template instead.",
    "docs_url": "https://docs.avox.com/api/errors#outside_messaging_window",
    "request_id": "req_4f1c2a9b8e7d6c5b4a3f2e1d",
    "meta_code": 131047
  }
}
```

## Access and permissions

| Code | Meaning | What to do |
| --- | --- | --- |
| `190` | Access token expired or invalid | Reconnect the number from [Connections](https://docs.theavoxai.com/connections). |
| `10`, `200` | Permission denied | Avox's permission for this number was removed or changed on Meta's side. Reconnect the number. |
| `131005` | Access denied | Same as above - reconnect the number. |
| `131031` | Account has been locked | Meta restricted the WhatsApp Business Account. Check WhatsApp Manager (**Open in Meta** on the connection's page). |
| `368` | Temporarily blocked for policy violations | Review the policy notice in WhatsApp Manager. |

## Rate and volume limits

| Code | Meaning | What to do |
| --- | --- | --- |
| `4` | Too many API calls | Slow down and retry later. |
| `80007` | WhatsApp Business Account rate limit reached | Slow down across every number on the account. |
| `130429` | Throughput limit reached | The number is sending faster than Meta allows. Spread messages out. |
| `131048` | Spam rate limit hit | Too many recipients blocked or reported the number. Review who you message and what you send. See [Quality and limits](https://docs.theavoxai.com/whatsapp/quality-and-limits). |
| `131056` | Pair rate limit hit | Too many messages to the same person in a short time. Wait before messaging them again. |

## Recipient and delivery

| Code | Meaning | What to do |
| --- | --- | --- |
| `131021` | Recipient can't be the sender | Send to a different number than the connected one. |
| `131026` | Message undeliverable | The number may not use WhatsApp, or can't receive this message right now. |
| `131030` | Recipient not in the allowed list | Only applies to Meta's test setups, which can message a short list of numbers. Add the number there, or use your real business. |
| `131047` | Re-engagement message | More than 24 hours since the person last messaged you - send a template. See [Messaging window](https://docs.theavoxai.com/whatsapp/messaging-window). |
| `131049` | Not delivered to keep the ecosystem healthy | Meta limits how many marketing messages one person receives. Don't retry right away. |
| `131050` | The person stopped marketing messages | Respect the choice - send them only non-marketing messages. |
| `133010` | Phone number not registered | The sending number isn't registered with the Cloud API. Check it on [Health](https://docs.theavoxai.com/health). |
| `137000` | Identity key mismatch | The person's WhatsApp account changed (a recycled phone number or an account migration). Meta blocks the send when **Identity-Key Check** is on for the connection. Confirm the number with them. |

## Message content

| Code | Meaning | What to do |
| --- | --- | --- |
| `100` | Invalid parameter | A field doesn't match what WhatsApp expects. Compare it with [Message types](https://docs.theavoxai.com/avox-api/messages). |
| `131008` | Required parameter is missing | Add the missing field. |
| `131009` | Parameter value is not valid | Fix the value - for example, too many buttons or a title that's too long. |
| `131051` | Unsupported message type | Use a type WhatsApp supports for this case. |
| `131052` | Media download error | WhatsApp couldn't download your `link`. Make sure it's public HTTPS and the file type is allowed. |
| `131053` | Media upload error | The file couldn't be processed. Check its type and size. |

## Templates

| Code | Meaning | What to do |
| --- | --- | --- |
| `132000` | Parameter count mismatch | Send exactly as many parameters as the template has placeholders. |
| `132001` | Template doesn't exist | Check the name and language on [Templates](https://docs.theavoxai.com/templates). |
| `132005` | Text too long once filled in | Shorten the parameter values. |
| `132007` | Format character policy violated | Remove characters the template's policy doesn't allow, such as new lines in a parameter. |
| `132012` | Parameter format mismatch | Send each parameter in the format its placeholder expects. |
| `132015` | Template is paused | Usually from low quality. See [Template approval](https://docs.theavoxai.com/templates/approval). |
| `132016` | Template is disabled | Create a new template. |

## Account, number and payment

| Code | Meaning | What to do |
| --- | --- | --- |
| `131000` | Something went wrong | Usually temporary on Meta's side. Retry later. |
| `131042` | Business eligibility or payment issue | Check the payment method for the WhatsApp Business Account in WhatsApp Manager. |
| `130497` | Country restriction | The account can't message people in the recipient's country. |
| `133000` | Incomplete deregistration | The number's registration with Meta needs finishing. Reconnect it. |
| `133016` | Too many registration attempts | Wait before trying to register the number again. |

## Errors during Embedded Signup

If Meta's signup popup reports an error, the connection wizard shows **The connection didn't go
through**, Meta's own message word for word, [AVX-3002](https://docs.theavoxai.com/error-codes/avx-3002), and "Meta error"
with its number. Look that number up in Meta's WhatsApp Embedded Signup error reference. The
wizard's **Try this** list covers the usual fixes, and you can click **Retry connection**. See
[Embedded Signup](https://docs.theavoxai.com/whatsapp/embedded-signup) for what each step of the popup does.

## Errors in the dashboard

When Avox can't finish something with Meta for you in the dashboard - changing a template or Flow,
updating a number's settings, checking health - you see an Avox [AVX code](https://docs.theavoxai.com/error-codes) with a
plain-English message. With **WhatsApp API problem reports** on in [Compliance](https://docs.theavoxai.com/compliance), the
Switchboard's Owner also gets an email when requests Avox makes to Meta for you keep failing - at
most one per issue per week.