Format
{
"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 withX-Team-Id, or when a team-scoped resource is accessed without the right role. See Team context and the Teams & workspaces guide.
| 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. |