# Errors

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json

Errors are JSON, but two conventions live side by side, because this API is the web app’s own interface. Newer endpoints return a stable snake_case code in `error` and a sentence in `message`. Older endpoints return a sentence in `error` and no `message`. Each table below says which is which.

## Stable codes

The Reporting API, key management, webhook settings and the checks every key goes through return a code. Match on `error`.

**Error shape**

```json
{
  "error": "scope_denied",
  "message": "This API key isn't scoped for inbox. Mint a new key with the right scope on the API Keys page.",
  "requiredPermission": "inbox",
  "keyScopes": ["templates"]
}
```

| Status | error | When |
| --- | --- | --- |
| 400 | `invalid_*`, `since_after_to`, `window_too_large` | A parameter is missing or malformed. The code names it. |
| 403 | `key_expired` | The key has passed its expiry. |
| 403 | `read_only_key` | A read-only key attempted a write. |
| 403 | `scope_denied` | The key’s scopes do not cover this endpoint, or an admin-only endpoint was called with a scoped key. |
| 403 | `permission_denied` | The admin who created the key lacks the permission. |
| 403 | `admin_required` | An admin-only action by someone who is not an admin. |
| 403 | `api_not_in_plan` | The workspace is on Starter, which has no API. |
| 403 | `api_access_not_enabled` | The call is part of the full API, which is included in the Scale plan, and the key belongs to a Growth workspace. |
| 403 | `webhooks_not_in_plan` | The workspace is on Starter, which has no webhooks. |
| 403 | `event_requires_scale` | A webhook subscription asks for an event that is part of the Scale plan. |
| 403 | `feature_disabled_for_org` | A feature the call needs, such as the WhatsApp Cloud API, is switched off for the workspace. |
| 403 | `account_suspended`, `membership_revoked` | The admin who created the key is suspended or no longer in the workspace. |
| 404 | `not_found` | No such item in this workspace. A chat outside a member’s assignment also returns this. |
| 412 | `version_conflict` | A contact was edited by someone else; refetch and retry. |
| 429 | `rate_limited` | Over the per-key limit. See Retry-After and the Rate limits guide. |
| 500 | `internal_error` | Our side. Retry with backoff; it is safe for reads. |

## Sentences, on older endpoints

The sign-in check, sending, and the contact calls return the error as a sentence in `error`. The text can change, so match on the HTTP status, and for sending also on `errorCode`. Each call’s own page lists its errors.

| Status | Error as returned | When |
| --- | --- | --- |
| 401 | Unauthorized: No token provided | No credential was sent. |
| 403 | Forbidden: Invalid or revoked API key | The key does not exist or was revoked. An expired key is `key_expired` above. |
| 403 | Account suspended. Contact your admin. | The admin who created the key is suspended. |
| 400 | Phone number is required, Message text is required, Template name is required | A required field of a send call is missing. |
| 404 | Contact not found | No such contact, or one the caller cannot see. |
| 500 | An internal error occurred. Please try again. | Our side, on the contact calls. |
| 500 | The reason WhatsApp gave | WhatsApp refused a send. See the next section. |

## When a send fails

`POST /api/send-message` answers **500** when WhatsApp refuses the message. The reason is in `error`, and WhatsApp’s details are in `errorCode`, `errorTitle`, `errorSubcode` and `errorDetails`. Unlike other 5xx responses this is usually not a fault on our side, and sending the same request again will fail the same way, so read `errorCode` before you retry.

| errorCode | What it means | What to do |
| --- | --- | --- |
| 131047 | More than 24 hours since the customer last wrote, so free-form text and media are not allowed. | Send a template instead. |
| 131026 | The message could not be delivered to that number, for example it is not on WhatsApp. | Do not retry. Check the number. |
| 132001 | The template does not exist in that language. | Fix the template name or language. |
| 132000 | The number of template parameters does not match the template. | Send the right number of parameters. |
| 131049 | WhatsApp declined to deliver a marketing message to protect the customer experience. | Do not retry straight away. |
| 130429 | WhatsApp’s throughput limit was reached. | Retry with backoff. |

These are WhatsApp’s own codes. The full list is in Meta’s Cloud API error reference.