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

# Error codes

> Main error codes returned by the MsgFlash public API.

## Format

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": []
  }
}
```

***

## Authentication and API quotas

| Code                                 | HTTP | Description                                              |
| ------------------------------------ | ---- | -------------------------------------------------------- |
| `UNAUTHORIZED`                       | 401  | API key missing, invalid, or revoked. Check `x-api-key`. |
| `FORBIDDEN`                          | 403  | Resource not accessible with this key                    |
| `SUBSCRIPTION_INACTIVE`              | 403  | The account has no usable subscription for this action   |
| `API_RATE_LIMIT_EXCEEDED`            | 429  | More than 10 requests/second on the same key             |
| `MONTHLY_API_REQUEST_QUOTA_EXCEEDED` | 429  | Monthly API request quota exhausted                      |

***

## Plan limits

| Code                              | HTTP | Description                                        |
| --------------------------------- | ---- | -------------------------------------------------- |
| `MAX_INSTANCES_REACHED`           | 403  | Instance limit reached                             |
| `API_KEYS_NOT_AVAILABLE_ON_PLAN`  | 403  | API keys unavailable on the current plan           |
| `MAX_API_KEYS_REACHED`            | 403  | API key limit reached                              |
| `WEBHOOKS_NOT_AVAILABLE_ON_PLAN`  | 403  | Webhooks unavailable on the current plan           |
| `MAX_WEBHOOK_ENDPOINTS_REACHED`   | 403  | Webhook endpoint limit reached                     |
| `CAMPAIGNS_NOT_AVAILABLE_ON_PLAN` | 403  | Campaigns unavailable on the current plan          |
| `STATUSES_NOT_AVAILABLE_ON_PLAN`  | 403  | WhatsApp statuses indisponibles sur le plan actuel |
| `MAX_CONTACT_GROUPS_REACHED`      | 403  | Contact group limit reached                        |
| `FEATURE_NOT_AVAILABLE_ON_PLAN`   | 403  | Feature unavailable on the current plan            |

***

## Messages, templates, and validation

| Code                           | HTTP | Description                                                  |
| ------------------------------ | ---- | ------------------------------------------------------------ |
| `VALIDATION_ERROR`             | 400  | Body does not match the expected schema                      |
| `BAD_REQUEST`                  | 400  | Invalid request                                              |
| `TEMPLATE_INVALID`             | 400  | Placeholder invalid ou template incohérent                   |
| `TEMPLATE_VARIABLES_MISSING`   | 400  | One or more required variables could not be resolved         |
| `TEMPLATE_CONTEXT_UNAVAILABLE` | 400  | Requested context is not available (`instance` or `contact`) |
| `INVALID_DESTINATION`          | 422  | Invalid recipient number                                     |

***

## General

| Code                   | HTTP | Description                                        |
| ---------------------- | ---- | -------------------------------------------------- |
| `NOT_FOUND`            | 404  | Resource does not exist or is outside your account |
| `CONFLICT`             | 409  | Uniqueness conflict                                |
| `INTERNAL_ERROR`       | 500  | Server error                                       |
| `PROVIDER_TIMEOUT`     | 502  | WhatsApp provider timeout                          |
| `PROVIDER_UNAVAILABLE` | 502  | Provider temporarily unavailable                   |
| `PROVIDER_ERROR`       | 502  | Generic provider error                             |

***

## Teams & workspaces

These codes appear when the request mixes the wrong API key type with `X-Team-Id`, or when a team-scoped resource is accessed without the right role. See [Team context](/api-reference/teams/team-context) and the [Teams & workspaces guide](/guides/teams-workspaces).

| Code                               | HTTP | Description                                                                                                                                            |
| ---------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TEAM_KEY_REQUIRED`                | 403  | Personal API key (`msgf_live_…`) used with `X-Team-Id`. Use a team key (`msgf_team_…`) instead, or drop the header.                                    |
| `TEAM_KEY_NOT_ALLOWED`             | 403  | Team API key used on a personal-only `v1` route (`/me`, `/usage`, `/billing/subscription`, `/billing/usage`, `/billing/payments`). Use a personal key. |
| `TEAM_NOT_FOUND`                   | 404  | `X-Team-Id` is not a team you currently belong to (deleted, removed, or wrong ID).                                                                     |
| `TEAM_ACCESS_DENIED`               | 403  | Authenticated but the role is not allowed for this action (e.g. collaborator trying to manage team API keys).                                          |
| `TEAM_FEATURE_UNAVAILABLE`         | 403  | Account plan does not include team creation (Free). Upgrade to Pro or MAX.                                                                             |
| `TEAM_LIMIT_REACHED`               | 403  | Owner reached the maximum number of teams allowed by their plan.                                                                                       |
| `TEAM_SEAT_LIMIT_REACHED`          | 403  | Team already has the maximum number of members for the owner’s plan.                                                                                   |
| `INSTANCE_NOT_ASSIGNED`            | 403  | Collaborator targeting an instance that has not been assigned to them in this team workspace.                                                          |
| `INVITE_INVALID_OR_EXPIRED`        | 400  | Invitation token / id is unknown, already used, or past its 24h expiry.                                                                                |
| `INVITE_EMAIL_MISMATCH`            | 403  | The JWT user email does not match the invited address.                                                                                                 |
| `INVITE_DUPLICATE_MEMBER`          | 409  | Invitee is already an active member of the team.                                                                                                       |
| `PLAN_CHANGE_BLOCKED_ACTIVE_TEAMS` | 409  | Downgrade refused because the new plan cannot host the current teams / seats. Delete teams or reduce seats first.                                      |

### Console-only (JWT, dashboard or portal)

These appear only on `/api/billing/*` JWT routes when called with `X-Team-Id`:

| Code                               | HTTP | Description                                                                                                                       |
| ---------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| `BILLING_PAYMENTS_TEAM_OWNER_ONLY` | 403  | `GET /api/billing/payments` in team workspace is reserved to the team owner.                                                      |
| `BILLING_TEAM_MUTATION_FORBIDDEN`  | 403  | `POST` mutations (`checkout`, `cancel`, `downgrade`, `cancel-scheduled-change`) in team workspace are reserved to the team owner. |