# Avox API Errors

> Every error code the Avox API can return - what it means, the usual causes, whether to retry, and how to fix it.

Source: https://docs.theavoxai.com/api/errors

When a request to the [Avox API](https://docs.theavoxai.com/avox-api) doesn't go through, the response always has the same
shape, so your code can handle every failure the same way:

```json
{
  "ok": false,
  "error": {
    "code": "invalid_recipient",
    "message": "The \"to\" number isn't valid. Use the full international number with country code, digits only, like 15551234567.",
    "docs_url": "https://docs.theavoxai.com/api/errors#invalid_recipient",
    "request_id": "req_4f1c9a0b7e2d36a8c5b1f0e9",
    "details": [
      { "path": "to", "message": "Use the full international number, digits only, like 15551234567" }
    ]
  }
}
```

| Field | What it's for |
| --- | --- |
| `code` | A stable identifier. Codes are never renamed or removed, so it's safe to branch on. |
| `message` | Written for a person - fine to log or show your team. The wording may improve over time. |
| `docs_url` | Links straight to that code's entry on this page. |
| `request_id` | Also sent as the `X-Request-Id` header on every response. Include it when you contact [Support](https://docs.theavoxai.com/support). |
| `details` | Only on some errors: up to 10 `{ "path", "message" }` pairs saying which field to fix. |
| `meta_code` | Only when WhatsApp refused the message: WhatsApp's own numeric code. See [Meta error codes](https://docs.theavoxai.com/meta-error-codes). |
| `test` | Only on responses to a [test key](https://docs.theavoxai.com/avox-api/testing#1-test-mode) (`avx_test_...`): `true`, next to `ok`. The response also has the `Avox-Test-Mode: true` header. Test keys run every Avox check for real, and the [special test numbers](https://docs.theavoxai.com/avox-api/testing#special-test-numbers) return WhatsApp's refusals on purpose. |

Error responses also carry `Retry-After` (whole seconds) when waiting will fix the problem.

## Find a failed request in the dashboard

Every request made with one of your keys, successful or not, is on the **API logs** page in the
dashboard (Admins and Managers can open it):

1. Open **API logs** and stay on the **Sent** tab.
2. Paste the `request_id` (`req_...`) into the search box, or pick a code in the error code filter
   (**Any error code**) to see every request that failed the same way. Narrow it down by key, mode
   (**Live only** or **Test only**), connection or date.
3. Click the row. **Request details** show the time, HTTP status, error code (linked to this page),
   key, connection, masked recipient, request id, message id, latency and the calling IP address.
4. **Export CSV** downloads everything matching your filters.

A key's latest requests are also under **Recent requests** when you expand it in **Settings > API
Keys**. See [API logs](https://docs.theavoxai.com/connections/api-keys#api-logs).

> **Note**
>
> Requests that never named a real key - no `Authorization` header, a mistyped key, or a request
> refused by the per-address limits before the key was checked - can't be tied to your account,
> so they aren't listed. Log `X-Request-Id` on your side for those.

## Which errors are safe to retry?

| Retry? | Codes |
| --- | --- |
| Yes, after the `Retry-After` delay | `rate_limited`, `idempotency_in_progress` |
| Yes, after the `Retry-After` delay, with a new `Idempotency-Key` | `meta_rate_limited` |
| Yes, after a short wait | `internal_error` |
| Carefully - it may already be sent | `meta_unavailable` |
| After midnight UTC | `quota_exceeded` |
| Only after you fix something | Everything else |

When you retry, send the same `Idempotency-Key` header as the first attempt so a message is never
sent twice - except after a refusal from WhatsApp, which is kept against that key. See
[Idempotency](https://docs.theavoxai.com/avox-api/idempotency) and [Rate limits](https://docs.theavoxai.com/avox-api/rate-limits).

> **Note**
>
> Some problems are found by WhatsApp only after it accepts a message, so they arrive later as a
> `failed` status on [Logs](https://docs.theavoxai.com/logs) instead of as an error here (see
> [Delivery statuses and replies](https://docs.theavoxai.com/avox-api/webhooks)). The status
> carries WhatsApp's own code - look it up on [Meta error codes](https://docs.theavoxai.com/meta-error-codes).

## Your API key

### missing_api_key

**HTTP 401.** The request had no API key.

- **Common causes:** the `Authorization` header is missing, or your HTTP tool dropped it. Signing in
  to the dashboard doesn't count - this endpoint only accepts an API key, never a browser session.
- **How to fix it:** send `Authorization: Bearer avx_live_...` on every request, with your key read
  from an environment variable on your server. See [Authentication](https://docs.theavoxai.com/avox-api/authentication).
- **Retry:** only after adding the header.

### invalid_api_key

**HTTP 401.** The key you sent isn't a key Avox recognises.

- **Common causes:** part of the key was cut off when copying, there's an extra space or quote
  around it, or the header doesn't start with `Bearer `.
- **How to fix it:** copy the key again from where you stored it. If you no longer have it, an
  Admin creates a new key - a key is only shown once, when it's created.
- **Retry:** only with the correct key.

> **Warning**
>
> Many failed key attempts from the same address in a short time are temporarily refused with
> `rate_limited`. Fix the key before retrying.

### key_revoked

**HTTP 401.** This key worked once but has been revoked.

- **Common causes:** an Admin on your team revoked it, or Avox support revoked it to protect your
  account.
- **How to fix it:** create a new key for the same number and update your server's secret.
- **Retry:** only with a new key.

### key_expired

**HTTP 401.** This key had an end date, and it has passed.

- **Common causes:** the key was [rotated](https://docs.theavoxai.com/connections/api-keys#rotate-a-key) and the grace period
  you picked has ended.
- **How to fix it:** put the key that replaced it on your server (or create a new key) and update
  your server's secret.
- **Retry:** only with the new key.

### ip_not_allowed

**HTTP 403.** This key only works from certain IP addresses, and the request came from somewhere
else.

- **Common causes:** your server moved, or its outgoing address changed after a redeploy.
- **How to fix it:** call from an allowed address, or contact [Support](https://docs.theavoxai.com/support) to update the
  list. If you don't recognise the request, revoke the key - it may have leaked. The key also shows
  **Blocked request from an unknown address** in **Settings > API Keys**.
- **Retry:** only from an allowed address.

## Your account

### api_access_disabled

**HTTP 403.** API access is switched off for this account.

- **How to fix it:** contact [Support](https://docs.theavoxai.com/support) to ask for it to be switched back on.
- **Retry:** once support confirms it's on.

### api_not_in_plan

**HTTP 403.** The account's plan doesn't include API access.

- **Common causes:** the account moved to a plan without API access, or the plan it's on no longer
  includes it. Your keys aren't deleted - they stay listed in **Settings > API Keys** and stop
  sending while the plan lacks API access. New keys can't be created or rotated meanwhile.
- **How to fix it:** an Admin moves to a plan with API access from **Billing > Change plan** in the
  dashboard (the plan cards list **API access** on the plans that include it). The same keys work
  again as soon as the new plan starts (allow up to a minute). See
  [API access and your plan](https://docs.theavoxai.com/connections/api-keys#api-access-and-your-plan).
- **Retry:** once the plan includes API access.

### account_suspended

**HTTP 403.** The account this key belongs to is suspended, so nothing can be sent with it.

- **How to fix it:** contact [Support](https://docs.theavoxai.com/support).
- **Retry:** once the account is active again.

### subscription_inactive

**HTTP 402.** The account doesn't have an active plan.

- **Common causes:** the plan was cancelled or ended, it's paused, or a payment problem stopped it.
  While a failed payment is still being retried, sending keeps working.
- **How to fix it:** renew or resume the plan, or update the payment, on the [Billing](https://docs.theavoxai.com/billing)
  page. Sending works again as soon as the plan is active.
- **Retry:** once the plan is active.

## Your WhatsApp number

Every key belongs to exactly one WhatsApp number. These errors are about that number.

### connection_not_found

**HTTP 404.** The number this key was made for has been removed.

- **How to fix it:** create a new key for one of your current numbers. See
  [Connections](https://docs.theavoxai.com/connections).
- **Retry:** only with a key for an existing number.

### connection_paused

**HTTP 409.** The number is paused, so it can't send.

- **Common causes:** an Admin paused it, it was paused because of a billing problem, or support
  paused it.
- **How to fix it:** resume it from the [Connections](https://docs.theavoxai.com/connections) page. If it was paused for
  billing, fixing the payment on [Billing](https://docs.theavoxai.com/billing) resumes it; if support paused it, contact
  [Support](https://docs.theavoxai.com/support).
- **Retry:** once the number is resumed. The same key works again straight away.

### connection_inactive

**HTTP 409.** The number isn't connected right now.

- **Common causes:** it's still being set up (**Connecting**), it was disconnected, or setup ended
  in **Error**.
- **How to fix it:** check the number's status on the [Connections](https://docs.theavoxai.com/connections) and
  [Health](https://docs.theavoxai.com/health) pages.
- **Retry:** once the number shows **Connected**.

### connection_not_ready

**HTTP 409.** The number needs to be reconnected before it can send.

- **Common causes:** WhatsApp's permission for Avox to send for this number expired or was removed
  on Meta's side.
- **How to fix it:** reconnect the number from the [Connections](https://docs.theavoxai.com/connections) page.
- **Retry:** after reconnecting. If you sent an `Idempotency-Key`, it's freed, so the retry runs as
  a new request.

### switchboard_paused

**HTTP 409.** The Switchboard this key belongs to is paused, so nothing can be sent from it.

- **Common causes:** an Admin paused the whole Switchboard in **Settings > Switchboard**, or the
  account was paused from **Settings > Delete account**. Pausing stops every number, automation
  and forwarded message in it, and keeps all the data.
- **How to fix it:** an Admin resumes it in **Settings > Switchboard** (or with **Resume my
  account** on **Settings > Delete account**, for an account pause). Resuming a single number on
  [Connections](https://docs.theavoxai.com/connections) isn't enough while the Switchboard is paused.
- **Retry:** once the Switchboard is resumed. The same key works again straight away.

## Limits

### rate_limited

**HTTP 429.** Too many requests in a short time.

- **Common causes:** a loop sending without a pause, many workers sharing one key, a key's own
  per-minute rule, or repeated attempts with a wrong key from one address.
- **How to fix it:** wait the number of seconds in the `Retry-After` header, then retry. For bulk
  sends, spread messages out instead of sending them all at once. See
  [Rate limits](https://docs.theavoxai.com/avox-api/rate-limits).
- **Retry:** yes, after `Retry-After`.

### quota_exceeded

**HTTP 429.** This key has used up its daily allowance.

- **How to fix it:** it resets at midnight UTC - `Retry-After` says how many seconds that is. If you
  regularly need more, contact [Support](https://docs.theavoxai.com/support). The key also shows **Hit its daily limit** in
  **Settings > API Keys**.
- **Retry:** after midnight UTC.

## The request itself

### payload_too_large

**HTTP 413.** The request body is over 64 KB.

- **How to fix it:** send media by `link` or `id` rather than embedding it, and send one message
  per request.
- **Retry:** only with a smaller body.

### invalid_payload

**HTTP 400.** The body isn't valid JSON, isn't a JSON object, or a field is missing, the wrong type,
or too long.

- **Common causes:** a body that isn't JSON (send it with `Content-Type: application/json`), a
  missing `type`, a text message over 4096 characters, a caption or a button or list message's
  text over 1024, a media message with
  both `id` and `link` (or neither), or a template parameter over 1024 characters.
- **How to fix it:** read `details` - each entry names the field (`path`) and what's wrong with it.
  Every limit is on [Message types](https://docs.theavoxai.com/avox-api/messages).
- **Retry:** only after fixing the body.

### invalid_recipient

**HTTP 400.** The `to` number isn't a valid phone number.

- **Common causes:** a missing country code, a leading `0`, letters, or a local-format number.
- **How to fix it:** send the full international number, like `15551234567` or `+44 7700 900123`.
  Spaces, dashes, dots, brackets and a leading `+` are fine; they're removed before sending.
- **Retry:** only with a corrected number.

### unsupported_message_type

**HTTP 400.** The `type` field isn't one the API sends.

- **How to fix it:** use one of `text`, `template`, `image`, `video`, `audio`, `document`,
  `sticker`, `location`, `contacts`, `interactive` or `reaction`. See
  [Message types](https://docs.theavoxai.com/avox-api/messages).
- **Retry:** only with a supported type.

### invalid_idempotency_key

**HTTP 400.** The `Idempotency-Key` header isn't usable.

- **How to fix it:** use 1 to 255 visible characters with no spaces - a UUID per message works
  well. See [Idempotency](https://docs.theavoxai.com/avox-api/idempotency).
- **Retry:** with a valid key.

### idempotency_conflict

**HTTP 409.** This `Idempotency-Key` was already used in the last 24 hours with this API key for a
different message.

- **Common causes:** reusing one fixed value for every message, changing the body between retries,
  or retrying a corrected message after WhatsApp refused the first version.
- **How to fix it:** make a new value for each new message, and reuse it only when retrying that
  exact message.
- **Retry:** with a new `Idempotency-Key`.

### idempotency_in_progress

**HTTP 409.** A request with this `Idempotency-Key` is still being processed.

- **How to fix it:** wait the `Retry-After` delay, then retry with the same key - once the first
  request finishes you'll get its result.
- **Retry:** yes, after `Retry-After`, with the same key.

## Refused by WhatsApp

These mean the request passed every Avox check and was handed to WhatsApp, which refused it.
`meta_code` carries WhatsApp's own code when there is one. With an `Idempotency-Key`, these results
are kept for 24 hours, so a retry with the same key returns the same error.

### template_not_found

**HTTP 422.** WhatsApp has no approved template with that name in that language.

- **Common causes:** a typo in the name, a template that's still in review, or the right name with a
  language it wasn't approved in (`en` and `en_US` are different).
- **How to fix it:** check the exact name and language on the [Templates](https://docs.theavoxai.com/templates) page.
- **Retry:** only with a corrected name or language.

### template_unavailable

**HTTP 422.** The template exists but WhatsApp has paused or disabled it, usually because of
negative feedback from recipients.

- **How to fix it:** check its status on the [Templates](https://docs.theavoxai.com/templates) page, and edit or replace it.
  See [Template approval](https://docs.theavoxai.com/templates/approval).
- **Retry:** once the template is active again, or with another template.

### template_params_invalid

**HTTP 422.** The values you sent don't fit the template.

- **Common causes:** too many or too few parameters, a parameter in the wrong format (for example,
  text where the template expects a currency), or a value too long once filled in.
- **How to fix it:** compare your `components` with the template's placeholders, in order. See
  [Message types](https://docs.theavoxai.com/avox-api/messages#template).
- **Retry:** only with corrected parameters.

### outside_messaging_window

**HTTP 422.** It's been more than 24 hours since this person last messaged you, so WhatsApp only
allows a template.

- **How to fix it:** send an approved `template` message. Once they reply, you can send other types
  again for 24 hours. See [Messaging window](https://docs.theavoxai.com/whatsapp/messaging-window).
- **Retry:** as a template.

### recipient_unreachable

**HTTP 422.** WhatsApp couldn't deliver to this number.

- **Common causes:** the number doesn't use WhatsApp, it's your own sending number, the person's
  WhatsApp account changed (when the connection's **Identity-Key Check** is on), or WhatsApp is
  limiting how many marketing messages they receive.
- **How to fix it:** check the number with the person. Don't retry the same message in a loop.
- **Retry:** no.

### meta_rate_limited

**HTTP 429.** WhatsApp is limiting how fast this number can send, or how often you can message one
person.

- **How to fix it:** slow down and retry after the `Retry-After` delay. See
  [Quality and limits](https://docs.theavoxai.com/whatsapp/quality-and-limits).
- **Retry:** yes, after `Retry-After`. Because this result is kept against an `Idempotency-Key`,
  retry with a new key.

### meta_rejected

**HTTP 422.** WhatsApp refused the message for another reason.

- **Common causes:** content that breaks WhatsApp's rules, a media link WhatsApp can't download,
  or a field WhatsApp doesn't accept for this message type (for example, too many buttons).
- **How to fix it:** look up `meta_code` on [Meta error codes](https://docs.theavoxai.com/meta-error-codes). WhatsApp's own
  wording isn't passed through, so `meta_code` is the detail to go on.
- **Retry:** only after fixing the message.

### meta_unavailable

**HTTP 502.** WhatsApp didn't answer in time, so it's unclear whether the message went out.

- **How to fix it:** wait a minute. The `Idempotency-Key` is freed, so a retry - even with the same
  key - sends the message again. If a duplicate would matter, check [Logs](https://docs.theavoxai.com/logs) for a status on
  the message, or check with the person, first.
- **Retry:** carefully, as above.

## Our side

### internal_error

**HTTP 500.** Something went wrong at Avox. Nothing was sent.

- **How to fix it:** retry after a short wait. If a retry with the same `Idempotency-Key` returns
  `idempotency_in_progress`, wait the `Retry-After` delay and try again. If it keeps happening,
  contact [Support](https://docs.theavoxai.com/support) with the `request_id`.
- **Retry:** yes, after a short wait.