Avox API Errors

When a request to the Avox API doesn't go through, the response always has the same shape, so your code can handle every failure the same way:

{
  "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" }
    ]
  }
}

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.

Which errors are safe to retry?#

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 and Rate limits.

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.
• 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.

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 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 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 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.
• 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.
• 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 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.
• 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 page. If it was paused for billing, fixing the payment on Billing resumes it; if support paused it, contact 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 and 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 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 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.
• 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. 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.
• 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.
• 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.
• 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 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 page, and edit or replace it. See Template 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.
• 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.
• 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.
• 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. 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 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 with the request_id.
• Retry: yes, after a short wait.