API error codes (mpbx-api)

These codes are returned in the code member of application/problem+json bodies (see docs/api/CONVENTIONS.md). The generic kind codes (MPBX-NOT-FOUND, MPBX-INVALID-ARGUMENT, ...) are in common.md.

Code	HTTP	Meaning	What to do
MPBX-INVALID-QUERY	400	A limit, sort or filter parameter is invalid: unknown or non-filterable field, bad operator, wrong value type, too many filters. errors[].field names the parameter.	Fix the parameter; see the allowed fields in the endpoint's docs.
MPBX-INVALID-CURSOR	400	The cursor is malformed or was issued for a different filter or sort.	Restart from the first page; never edit or reuse cursors across queries.
MPBX-PRECONDITION-REQUIRED	428	A PUT, PATCH or DELETE had no If-Match header.	GET the resource and send its ETag as If-Match.
MPBX-PRECONDITION-FAILED	412	If-Match does not match: the resource changed since you read it.	GET again, reapply your change, retry with the new ETag.
MPBX-IDEMPOTENCY-KEY-INVALID	400	Idempotency-Key is empty, longer than 255 characters, not visible ASCII, or sent more than once.	Send one key of 1 to 255 visible ASCII characters (a UUID works).
MPBX-IDEMPOTENCY-KEY-REUSED	422	The same caller already used the key on this route with a different path, query or body.	Use a new key for a new request; reuse a key only to retry the identical request.
MPBX-IDEMPOTENCY-IN-PROGRESS	409	A request with this key is still running. Honour Retry-After.	Retry shortly with the same key.
MPBX-IDEMPOTENCY-UNAVAILABLE	503	The company holds too many Idempotency-Key records (or the install-wide bound is reached). Nothing was run.	Honour Retry-After and retry with the same key; send keys only on requests that need them.
MPBX-PAYLOAD-TOO-LARGE	413	The request body exceeds the 1 MiB buffered by the idempotency layer.	Send a smaller body.
MPBX-ROUTE-NOT-FOUND	404	No route matches the path. Also returned for /api/docs when the docs toggle is disabled.	Check the path and API version.
MPBX-METHOD-NOT-ALLOWED	405	The path exists but not for this HTTP method.	Check the method in the API docs.
MPBX-LOCALE-NOT-FOUND	404	GET /api/v1/i18n/{locale} for a locale that is not installed.	Use one of the shipped locale tags or upload the language pack first.
MPBX-RATE-LIMITED	429	Too many sign-in, refresh, TOTP or onboarding-exchange attempts from this client in the last minute (defaults: 10 logins, 60 refreshes and logouts, 10 TOTP calls, 10 QR onboarding exchanges; http.login_rate_per_min, http.onboarding_rate_per_min and friends). One client is an IPv4 address or an IPv6 /64 network (all addresses of one IPv6 subscriber share the budget). Sent before any password is checked. Carries Retry-After. In a flood of distinct clients that fills the limiter's table with throttled clients, clients that are not in the table yet get this answer too until windows expire (the limiter fails closed).	Wait for Retry-After seconds. Behind a reverse proxy list it in http.trusted_proxies (or set http.trust_forwarded_for), or all users share one address. With several API nodes the budgets are shared through Valkey.
MPBX-ME-SESSION-REQUIRED	403	PUT /me/language or POST /me/password was called with an API key. Only a signed-in person changes their own language or password (FU-WEB04-1).	Sign in and call it with the session's access token.
MPBX-TENANT-HOST-UNKNOWN	404	The web address (Host) is <slug>.<http.base_domain> but no company has that handle. There is no fallback to the default company.	Check the address; company handles are listed in the Companies admin area.
MPBX-CROSS-ORIGIN	403	POST /api/v1/auth/login, /refresh or /logout came from a browser page of another origin (an Origin header that is not this server's own address), for example a page on a sibling company subdomain or a forged form on another site. The refresh cookie is never set or used for it.	None for users. Native clients send no Origin header.
MPBX-UNSUPPORTED-MEDIA-TYPE	415	A sign-in route (/api/v1/auth/login, /refresh, /logout, /totp/verify) got a request body whose Content-Type is not application/json (or application/*+json). An empty body (browser refresh and logout) needs no Content-Type. This keeps HTML forms of other sites (text/plain, form encodings) away from the auth routes.	Send the body with Content-Type: application/json.

Configuration API (W2-API-01)

Returned by the users, departments, extensions, devices and roles routes (docs/guides/config-api.md). Role and permission errors (MPBX-RBAC-*) and password policy errors (MPBX-AUTH-PASSWORD-POLICY) are in auth.md.

Code	HTTP	Meaning	What to do
MPBX-API-NOT-CONFIGURED	503	The host did not inject the configuration services into the API router (a deployment or wiring error), or the audit routes run without clickhouse.url (the records wait in the Postgres outbox until it is set, see audit guide).	Operators: start the API role with the database configured; clients retry later.
MPBX-INVALID-BODY	400	The JSON body is malformed, has a wrong type or lacks a required field. errors[0].message says where.	Fix the body; the OpenAPI document has the schema and an example.
MPBX-UNSUPPORTED-MEDIA-TYPE	415	A configuration route got a body without Content-Type: application/json (the sign-in routes are listed above).	Send Content-Type: application/json.
MPBX-USER-EMAIL-TAKEN	409	Another user of the company already has this e-mail address (compared case-insensitively).	Use another address, or change the existing user.
MPBX-USER-SELF	409	The administrator tried to disable or delete their own account.	Ask another administrator.
MPBX-ACCOUNT-OUTRANKS	403	The account you tried to act on (reset its password or 2FA, disable, delete, change its e-mail address or department) holds permissions you do not hold.	Ask someone who holds at least the same permissions.
MPBX-ACCOUNT-SYSTEM	403	The account holds a system role (System Owner or System Admin) and you do not outrank it. System Owner > System Admin > none, and only a System Owner changes another System Owner; company principals (a company Owner included) and API keys have no system rank. Covers field changes, disable, delete, password or 2FA reset, role assignment or removal, the account's extension, and CSV import rows (W1-SEC-01-M1, rbac.md). Also in auth.md.	Ask a System Owner (for a System Admin, a System Owner; for a System Owner, another System Owner), acting from system scope inside the company.
MPBX-EXTENSION-NUMBER-TAKEN	409	Another extension of the company has this number.	Choose a free number.
MPBX-EXTENSION-USER-TAKEN	409	The user already owns an extension (a user has at most one).	Change or delete the existing extension first.
MPBX-EXTENSION-NOT-USER-KIND	400	An owner (user_id) was given to an extension whose kind is not user.	Leave user_id out, or create a user extension.
MPBX-DEPARTMENT-NAME-TAKEN	409	Another department of the company has this name.	Choose another name.
MPBX-DEPARTMENT-DEFAULT	409	The Default department cannot be deleted or moved under another department (it can be renamed).	Leave it in place.
MPBX-DEPARTMENT-NOT-EMPTY	409	The department still has users or sub-departments.	Move or delete them first.
MPBX-DEPARTMENT-CYCLE	400	The new parent would make the department its own ancestor.	Choose a parent outside the department's own subtree.
MPBX-AVATAR-INVALID	400	The profile photo is not a PNG, JPEG or WebP picture (the bytes are checked, not the name or Content-Type), is damaged, is animated, is larger than 1 MiB or 2048 by 2048 pixels, or is empty. Nothing is stored.	Send a still PNG, JPEG or WebP picture within the limits.
MPBX-MEMBERSHIP-PRIMARY	409	DELETE /users/{id}/departments/{department_id} named the user's primary department.	Move the user with PATCH /users/{id} (department_id) instead.
MPBX-DEVICE-MAC-TAKEN	409	Another device of the company has this MAC address.	Check for a duplicate device, or use the other MAC.
MPBX-DEVICE-REVOKED	409	The device is revoked: it cannot be changed or revoked again, get credentials or an onboarding token.	Create a new device.
MPBX-IMPORT-MALFORMED	400	The CSV file is empty, is not UTF-8, has unbalanced quotes, lacks the email column or has unknown or repeated columns.	Fix the file; export users to get a correct template.
MPBX-IMPORT-TOO-LARGE	400	The CSV file is larger than 5 MiB or has more than 2000 data rows.	Split the file.
MPBX-IMPORT-INVALID	422	POST /users/import?dry_run=false found invalid rows and wrote nothing. errors[] lists up to 100 rows with the reason.	Run with dry_run=true, fix the rows in the report, and apply again.

Dial plan (W2-DP-01)

Returned by the dial plan routes (/dial-plan/*, /outbound-rules, /inbound-routes, /calling-profiles); see the dial plan guide. Validation errors are the generic MPBX-INVALID-ARGUMENT (400) with the field; a user's calling profile can also return MPBX-ACCOUNT-OUTRANKS and MPBX-ACCOUNT-SYSTEM (above).

Code	HTTP	Meaning	What to do
MPBX-OUTBOUND-RULE-NAME-TAKEN	409	Another outbound rule of the company has this name.	Choose another name.
MPBX-INBOUND-ROUTE-TAKEN	409	The company already routes this DID on this trunk, or already has this catch-all (one per trunk and one for the company).	Change the existing route instead.
MPBX-INBOUND-BLOCK-EXISTS	409	The inbound blocklist already holds this number, prefix or anonymous entry for this DID (W6-TEL-03a).	Change the existing entry instead.
MPBX-INBOUND-CALLER-RULE-NAME-TAKEN	409	Another caller-ID routing rule of the company has this name (W6-TEL-03a).	Choose another name.
MPBX-HOLIDAY-MESSAGE-EXISTS	409	The queue, ring group or department already has a holiday message (W6-TEL-03a).	Change the existing message instead.
MPBX-INBOUND-EXTERNAL-NOT-PERMITTED	403	An inbound route or caller-ID rule to an outside number: the principal extension's calling profile and outbound rules do not allow dialling it (toll-fraud gate, W6-TEL-03a).	Allow the destination class in the principal's calling profile, or choose a principal that may dial it.
MPBX-CALLING-PROFILE-EXISTS	409	The company, department or user already has a calling profile.	Change the existing profile (PATCH /calling-profiles/{id}).
MPBX-EMERGENCY-NUMBER-NAME-TAKEN	409	Another emergency number of the company has this name (W2-EMR-01).	Choose another name, or change the existing number (PATCH /emergency-numbers/{id}).
MPBX-EMERGENCY-NUMBER-APPROVAL	403	The number is not one of the known emergency short codes (911, 112, 999, ...; emergency guide), or a route prepends digits or + to it, or a route sends it in a format other than dialled (e164, e164_digits and national go through the company's numbering, whose dial rules can turn it into any number). Also returned by PATCH /dial-plan/settings when a numbering change (country code, prefixes, dial rules) would change the number such an approved route sends. An emergency number skips every call limit, so only the System Owner may set it (W2-API-02, PR #126 review). Already-approved numbers keep their other fields editable.	Ask the System Owner to set it, acting in the company (X-Mpbx-Tenant).
MPBX-EXTENSION-EMERGENCY-NUMBER	409	The extension number is an enabled emergency number of the company: emergency numbers are decided before extensions, so the extension could never be called (W2-API-02, FU-EMR01-8).	Choose another number, or disable the emergency number first.

Ring groups (W3-TEL-06)

Returned by /ring-groups; see the ring group guide. The shared conditions (MPBX-EXTENSION-NUMBER-TAKEN for the group's number, MPBX-EXTENSION-EMERGENCY-NUMBER, validation, 404, 412 and 428) are the ones above.

Code	HTTP	Meaning	What to do
MPBX-RING-GROUP-NAME-TAKEN	409	Another ring group of the company has this name.	Choose another name.
MPBX-RING-GROUP-NO-ANSWER-UNAVAILABLE	400	Retired (FU-RG-1): voicemail is accepted as a no-answer destination; the code is no longer returned and stays reserved.	None.
MPBX-CONFERENCE-ROOM-NAME-TAKEN	409	Another conference room of the company has this name (W6-TEL-07).	Choose another name.

Queues, voicemail defaults, recording policies (W3-API-02)

Returned by /queues, /queue-settings, /voicemail/settings, /recording-settings, /recording-policies and the extension routes. The other conditions (validation, 404, 412 and 428) are the ones above; a recording target that does not exist is MPBX-REC-INVALID (recording).

Code	HTTP	Meaning	What to do
MPBX-QUEUE-NAME-TAKEN	409	Another queue of the company has this name.	Choose another name.
MPBX-EXTENSION-HAS-MAILBOX	409	The extension's voicemail mailbox holds messages or greetings, so the extension cannot be deleted yet (an empty mailbox goes with its extension).	Download what must be kept, delete the mailbox (DELETE /voicemail/mailboxes/{id}), then delete the extension.

SIP trunks and DIDs (W2-API-02)

Returned by /trunks, /trunks/{id}/dids, /trunk-dids and the system views /system/trunk-numbers and /system/trunk-approvals; see the trunk guide. A trunk setting the engine refuses is MPBX-TRUNK-INVALID (400, trunk errors).

Code	HTTP	Meaning	What to do
MPBX-TRUNK-NAME-TAKEN	409	Another trunk of the company has this name.	Choose another name.
MPBX-TRUNK-DID-OVERLAP	409	A DID of the list overlaps another entry of the list or a DID of another trunk of the company (the message names the trunk).	Remove the overlap, or move the number from the other trunk first.
MPBX-TRUNK-DID-TAKEN	409	A number (a DID, a range holding it, or a trunk's main number) belongs to another company on this system: a number belongs to one company only. The message never says which company, trunk or range holds it; the refusal is audited (trunk.did_refused).	Check the number. If it is yours, the system administrator finds the holder with GET /system/trunk-numbers and settles it.
MPBX-TRUNK-DID-LIMIT	409	The company would hold more than 100 000 DIDs (enforced by the database).	Remove unused ranges, or ask the system administrator.
MPBX-TRUNK-IN-USE	409	The trunk cannot be deleted: an outbound rule or an emergency number routes to it, or inbound routes are limited to it (errors lists them; GET /trunks/{id}/usage shows them beforehand).	Change those first, or delete with detach_inbound_routes=true to make the inbound routes apply to any trunk.
MPBX-TRUNK-EMERGENCY-ROUTE	409	Disabling the trunk, or turning its outbound calls off, would leave an enabled emergency number without a usable route (errors lists it).	Give the emergency number a route on another trunk, or disable it, first.
MPBX-TRUNK-APPROVAL-SYSTEM-ONLY	403	Only a system administrator acting in the company approves an inbound allow-list (inbound_acl_approved).	Ask the system administrator; GET /system/trunk-approvals lists the pending ones.
MPBX-TRUNK-HOST-NOT-ALLOWED	403	A company may not point host, outbound_proxy or registrar at an internal address (loopback, private, link-local, carrier-grade NAT, unique-local, ...), given literally or as a name resolving to one (FU-TRK01-12).	Use the carrier's public address or name; a system administrator may set an internal one (a carrier on a private link).

Office hours (W3-TEL-05)

Returned by the office-hours routes (/schedules, /schedule-status, /holiday-sets); see the office hours guide. Validation errors (an unknown time zone, an overlapping span, a wrong holiday field, an override that ends in the past) are the generic MPBX-INVALID-ARGUMENT (400) with the field as a JSON pointer in errors[].

Code	HTTP	Meaning	What to do
MPBX-SCHEDULE-NAME-TAKEN	409	Another schedule of the company has this name.	Choose another name.
MPBX-SCHEDULE-EXISTS	409	The company (or the department) already has its schedule; there is one company schedule and one per department.	Change the existing schedule (PATCH /schedules/{id}), or create a custom schedule.
MPBX-HOLIDAY-SET-NAME-TAKEN	409	Another holiday set of the company has this name.	Choose another name.
MPBX-HOLIDAY-SET-IN-USE	409	A schedule still uses the holiday set, so deleting it would silently turn holidays into ordinary days.	Detach it first (PATCH /schedules/{id} with no_holiday_set: true).
MPBX-HOLIDAY-SET-FULL	409	The holiday set holds the most holidays it may (1000).	Delete holidays that are past, or use another set.
MPBX-CALENDAR-INVALID	400	The uploaded file is not an iCalendar file (no BEGIN:VCALENDAR, not UTF-8), is larger than 1 MiB or has more than 2000 events.	Export the calendar again as .ics, or split it.

Change history and revert (W4-ADM-02)

Returned by POST /api/v1/config-history/{id}/revert (and shown as revert.code by GET /api/v1/config-history/{id}); see the change history guide. A refusal of the operation the revert calls (validation, MPBX-RBAC-FORBIDDEN, MPBX-RBAC-ESCALATION, MPBX-EXTENSION-NUMBER-TAKEN, 412, ...) is returned as it is.

Code	HTTP	Meaning	What to do
MPBX-HISTORY-CONFLICT	409	Later changes touch the same fields of the object (conflicts[], kind newer_change, lists them with their diffs), or a later change of another object mentions the value the change set (kind dependent_change), or a field no longer has the value the change gave it and no history entry says why (kind value_changed, with expected and actual). Nothing was changed.	Look at the listed changes. Revert the newer ones first (newest first), or set the value by hand.
MPBX-HISTORY-NOT-REVERTIBLE	409	This kind of change has no way back: a delete (other than a removed role assignment; the entry shows the last values so the object can be created again), the object no longer exists, a field with no reverter, or the revert would change nothing.	Create or change the object through the normal operations.
MPBX-HISTORY-SECRET-FIELD	409	The change touched a password, a two-factor secret or device credentials. The old value is not kept anywhere, so it cannot be restored.	Set the password again (password reset) or re-enrol the device or 2FA.
MPBX-HISTORY-NO-SNAPSHOT	409	The entry recorded only the names of the changed fields (the change came through a path that does not pass values yet), so there is nothing to restore.	Change the object by hand.
MPBX-HISTORY-ALREADY-REVERTED	409	A later change already reverted this one, and that revert is still in force.	Revert the reverting entry if you want the change back.

Events WebSocket and click-to-call (W3-API-01)

Returned by GET /api/v1/events (before the upgrade, as problem+json; after it, in error frames and close codes) and by POST /api/v1/calls/click-to-call. Guide: events-ws.md.

Code	HTTP / close	Meaning	What to do
MPBX-NOT-IMPLEMENTED	501	The route's contract is published but its behaviour is not available in this release. No route answers it today (POST /api/v1/calls/click-to-call did until MVP-GAP-04; without a call engine it now answers 503 MPBX-CALL-ENGINE-UNAVAILABLE, calls.md). The caller was authenticated and the body validated.	Do not retry. Build against the OpenAPI description; the route starts working in a later release without changes to the request or response.
MPBX-EVENTS-WS-UPGRADE-REQUIRED	426	A plain HTTP request reached GET /api/v1/events.	Open a WebSocket (HTTP/1.1 upgrade, version 13).
MPBX-EVENTS-WS-BAD-TOPIC	400 / error frame	A topic name is not one of call, leg, queue, presence, voicemail, config, audit.	Fix the name.
MPBX-EVENTS-WS-BAD-CURSOR	400 / error frame	The cursor is not an event id.	Send the cursor of an event you received.
MPBX-EVENTS-WS-CURSOR-TOO-LATE	error frame	A cursor came in a subscribe after the first one.	Reconnect with the cursor.
MPBX-EVENTS-WS-BAD-MESSAGE	error frame, close 1008	A client frame is not JSON of a known op, or is binary. More than 10 of these close the socket.	Send subscribe, unsubscribe, ping (and auth first when you sent no header).
MPBX-EVENTS-WS-NOT-AUTHENTICATED	error frame, close 4401	The first frame of a socket without a header credential was not auth.	Send {"op":"auth","token":...} first.
MPBX-EVENTS-WS-AUTH-TIMEOUT	close 4401	No auth frame within 5 s.	Send it right after connecting.
MPBX-EVENTS-WS-AUTH-FAILED	close 4401 / 4403	The auth frame's credential was refused; the preceding error frame carries the reason (MPBX-AUTH-*, MPBX-TENANT-*).	Sign in again.
MPBX-EVENTS-WS-ALREADY-AUTHENTICATED	error frame	An auth frame on an authenticated socket.	None; the socket keeps working.
MPBX-EVENTS-WS-CREDENTIAL-ENDED	close 4401	The access token expired, was revoked, or the user was disabled; found by the periodic re-check (every 60 s).	Refresh the token and reconnect with the cursor.
MPBX-EVENTS-WS-TOO-MANY	429 / close 4429	Too many open event connections for this user or key (default 20), for the company (5 000) or install-wide (10 000). Also the close reason of a connection closed to make room: a waiting-to-authenticate socket of the network holding the most waiting sockets, or the newest connection of the company holding the most when another company needs room in a full install. The 429 carries Retry-After.	Close sockets you do not use; share one socket per client; reconnect with your cursor after the Retry-After delay.
MPBX-EVENTS-WS-IDLE	close 4408	The client sent nothing, not even a pong, for 60 s.	Answer pings (browsers do) or send {"op":"ping"}; reconnect with the cursor.
MPBX-EVENTS-WS-SLOW-CONSUMER	close 1013	The client did not read its frames fast enough; the server never buffers without bound.	Read continuously; reconnect with the cursor.

Language packs and string overrides (W4-L10N-04)

Returned by /api/v1/i18n/packs, /i18n/overrides and /i18n/strings (guide). MPBX-LOCALE-NOT-FOUND (above) is also returned by the administration routes for a language the company neither ships nor uploaded.

Code	HTTP	Meaning	What to do
MPBX-LOCALE-TAG-INVALID	400	The language tag is not language[-Script][-REGION][-variant] made of letters and digits (for example sv, pt-PT, sr-Latn).	Use a BCP 47 tag; the shipped ones are en, es-MX, pt-BR, fr, de, it, ru, zh-Hans and ja.
MPBX-LOCALE-RTL-UNSUPPORTED	400	The language is written right to left (Arabic, Hebrew, Persian, Urdu, and so on). The clients have no right-to-left layout (DECISIONS Round 6).	Not supported in v1.
MPBX-LOCALE-PACK-INVALID	422	The pack failed validation and nothing was stored. errors[] lists up to 100 problems with the key: unknown key (not in the English source), broken ICU syntax, placeholders that differ from English, markup (<b>, <script>), control or bidirectional characters, a message over 2,000 characters, more than 10,000 keys, an empty pack, or a missing name for a new language.	Fix the listed keys and upload again. Run mpbx i18n validate <file> locally to see the same checks.
MPBX-LOCALE-PACK-EXISTS	409	POST /i18n/packs for a language that already has a pack.	GET the pack for its ETag and replace it with PUT /i18n/packs/{locale}.
MPBX-LOCALE-PACK-LIMIT	409	The company already holds 30 uploaded languages.	Delete a language you do not use.
MPBX-LOCALE-OVERRIDE-INVALID	422	The override key is not in the English source, or the text has broken ICU syntax, other placeholders than English, markup, control characters, or is empty or longer than 2,000 characters.	Fix the key or text; errors[] says which.
MPBX-LOCALE-OVERRIDE-LIMIT	409	The language already has 5,000 overrides.	Remove overrides you do not need.

SIP credentials, SIP profile and QR onboarding (W2-API-03)

Returned by /devices/{id}/credentials, /sip-settings, /sip-lock, /unlock, /onboarding-token, the /me/sip-profile and /me/devices routes and /onboarding/exchange (guide). Without the SIP services (a wiring error) these routes answer MPBX-API-NOT-CONFIGURED (above). A device on the extension of an account you may not manage is MPBX-ACCOUNT-OUTRANKS or MPBX-ACCOUNT-SYSTEM (above).

Code	HTTP	Meaning	What to do
MPBX-DEVICE-CHANGED	409	The device (or your extension) changed while new credentials were being issued, for example it was revoked or edited at the same moment. Nothing was changed and no password is valid.	Read the device again and retry.
MPBX-DEVICE-LIMIT	409	You already hold the most active devices allowed on your own extension (10 by default).	Revoke a device you no longer use (POST /me/devices/{id}/revoke), or ask an administrator.
MPBX-SIP-SESSION-REQUIRED	403	A /me/sip-profile or /me/devices route was called with an API key. Your own SIP devices are managed from a signed-in session only.	Sign in (POST /auth/login) and use the access token; administrators use the /devices routes.
MPBX-CDR-SESSION-REQUIRED	403	GET /me/calls or /me/calls/{id} was called with an API key. Your own calls are read from a signed-in session; the company-wide history is GET /cdr.	Sign in and use the access token, or use GET /cdr with call_history:read.
MPBX-SIP-NO-EXTENSION	404	You own no extension, so you have no SIP profile or devices.	Ask an administrator to give you an extension.
MPBX-ONBOARDING-TOKEN-INVALID	401	The onboarding code is unknown at this address, expired (10 minutes by default), already used, replaced by a newer code for the same device, or its device was revoked or its user disabled. One answer for every case.	Ask for a new QR code or link and scan it within its lifetime, at the address it names.

Desk-phone provisioning (W4-DEV-01)

Returned by the /devices/{id}/provisioning routes and /provisioning/... (guide). The phone-facing /prov/... routes have no error body: every refusal is an empty 404 (so nothing tells an attacker which part was wrong), over-budget clients get 429 MPBX-RATE-LIMITED, and a digest-protected URL answers 401 with a WWW-Authenticate: Digest challenge.

Code	HTTP	Meaning	What to do
MPBX-PROVISIONING-NO-MAC	409	The device has no usable MAC address (none, or one a phone cannot have: all zeros, a group address).	Set the MAC on the device (PATCH /devices/{id}) and try again.
MPBX-PROVISIONING-EXISTS	409	The device already has a provisioning profile.	Change it with PATCH, or issue a new URL with POST .../regenerate.
MPBX-PROVISIONING-NOT-FOUND	404	The device has no provisioning profile.	Create one with POST /devices/{id}/provisioning.
MPBX-PROVISIONING-LINK-LIMIT	409	The device already has 5 unused, unexpired signed provisioning links (W6-DEV-01b).	Revoke them (DELETE /devices/{id}/provisioning/links) or let them expire, then issue a new one.

Contacts (MVP-GAP-05)

Code	HTTP	Meaning	What to do
MPBX-CONTACT-NUMBER-TAKEN	409	Another contact of the same book (the company phonebook, or your personal contacts) already has this phone number; the digits of phone identify a contact.	Change the existing contact instead, or use a different number. A CSV import updates such a contact instead of failing.
MPBX-CONTACT-LIMIT	409	The book would hold more than its maximum: 200000 contacts in the company phonebook, 20000 personal contacts per user. An import that would pass the limit is rolled back as a whole.	Delete contacts you no longer need.
MPBX-CONTACT-IMPORT-BUSY	409	Another import of the same book (the company phonebook, or the same user's personal contacts) is still running, or the server already runs its two contact imports at once (all companies together; the answer then has Retry-After).	Wait for it to finish and retry.
MPBX-CONTACT-NO-PERSONAL	403	The account is not a user of the company the request acts in (a system administrator who entered a company), so it has no personal contacts there.	Use the company phonebook, or sign in as a user of the company.

The contact CSV import also answers with the import codes MPBX-IMPORT-MALFORMED (bad header, quoting or encoding, an upload that stalled or broke off), MPBX-IMPORT-TOO-LARGE (more than 100000 rows or 64 MiB) and MPBX-IMPORT-INVALID (422: invalid rows and no skip_invalid).

Web push for browsers (W6-RLY-WEB)

Returned by GET /me/web-push and PUT / DELETE /me/devices/{id}/web-push (guide). These routes take a signed-in session only (an API key is MPBX-SIP-SESSION-REQUIRED, above); a device that is not your own live device is MPBX-NOT-FOUND; more than 10 changes per minute are MPBX-RATE-LIMITED (429, Retry-After).

Code	HTTP	Meaning	What to do
MPBX-WEB-PUSH-INVALID	400	The body is not a Push API subscription: the endpoint is not an https:// URL (or is longer than 1024 characters), or keys.p256dh (65 bytes) or keys.auth (16 bytes) is missing or not base64url of that size.	Send PushSubscription.toJSON() of a subscription created with the application_server_key of GET /me/web-push.
MPBX-WEB-PUSH-NOT-BROWSER	409	The device is a phone whose mobile app registered a push token; a browser subscription would replace it.	Register the subscription for the browser's own device (the web softphone's device, POST /me/devices).
MPBX-WEB-PUSH-REFUSED	422	The push relay does not deliver to this browser's push service (not one of the known public push services of Chrome, Edge, Firefox and Safari; relay code RELAY-WEB-ENDPOINT-REFUSED).	Use a current evergreen browser; calls still ring while MonoPbx is open.
MPBX-WEB-PUSH-UNAVAILABLE	503	This server cannot send web push now: no push relay (air-gapped or not enrolled), the relay cannot be reached, the relay does not serve browsers, the entitlement grace is over, or the registration failed. GET /me/web-push then answers available: false.	Retry later; an operator checks the push relay status (docs/guides/push-wake.md).
MPBX-ACT-CODE-INVALID	400	The manual activation code is malformed, unknown, already used, expired, or bound to another install (relay code RELAY-ENROLL-CODE-INVALID).	Check the code; ask MonoPbx for a new one bound to this install (mpbx activate --show-key).
MPBX-ACT-RELAY-UNREACHABLE	503	Manual activation could not reach the push relay, or manual activation is off (relay.enroll = false or no MPBX_RELAY_INSTANCE_KEY).	Allow outbound HTTPS to the relay and retry; calls are not affected.
MPBX-ACT-RATE-LIMITED	503	More than 5 manual activation attempts (valid or not) in 15 minutes on this install (W7-SEC-01-C1 ACT-1).	Wait a few minutes and enter the code once more; check it for typos first.
MPBX-OAUTH-INVALID-REQUEST	400	An OAuth request of an MCP client is malformed (missing parameter, bad PKCE verifier or challenge). The token endpoint answers invalid_request.	Fix the client request (docs/guides/mcp.md).
MPBX-OAUTH-INVALID-CLIENT	400/401	Unknown MCP client, or the redirect URI is not registered for it. The authorization endpoint answers a plain 400 and never redirects.	Register the client again (POST /oauth/register) with the exact redirect URI.
MPBX-OAUTH-INVALID-GRANT	400	The authorization code or refresh token is unknown, spent, expired, revoked, or does not match the client, redirect URI, verifier or resource. A spent code or a rotated refresh token presented again revokes the grant.	Start the authorization again.
MPBX-OAUTH-INVALID-SCOPE	400	None of the requested scopes is a permission the signed-in user holds.	Ask for permissions the user has, or ask an administrator for a role.
MPBX-OAUTH-INVALID-TARGET	400	The resource is not this server's MCP endpoint (https://<host>/mcp).	Use the resource from /.well-known/oauth-protected-resource/mcp.
MPBX-OAUTH-INVALID-REDIRECT-URI	400	A registered redirect URI must be https://, or http:// on a loopback address, without a fragment.	Fix the client registration.
MPBX-OAUTH-TOKEN-INVALID	401	The MCP access token is unknown, expired, revoked, of another company, or for another resource. /mcp answers 401 with a WWW-Authenticate challenge.	Refresh the token or authorize again.
MPBX-OAUTH-TOO-MANY-CLIENTS	400	The company already has 500 registered MCP clients.	An operator removes unused clients (FU-W9-AI-13-2).
MPBX-STORAGE-QUOTA-EXCEEDED	507	The company is over 100 % of its storage quota: new call recordings, chat and SMS/MMS attachments, fax media and uploads are refused (guide). Calls are never blocked, voicemail works up to 110 %, nothing is deleted.	Free space (delete old recordings or files, shorten the retention) or ask the system administrator to raise the quota; the admin alert StorageQuotaExceeded is already raised.
MPBX-DISPOSITION-NOT-PARTICIPANT	403	PUT /me/agent/calls/{id}/disposition: the agent did not take part in the call (its call history record does not name them, CC-AGENT-006, G-020).	Tag only calls you handled.
MPBX-DISPOSITION-CALL-PENDING	409	PUT /me/agent/calls/{id}/disposition: the call is not in the call history yet (the record is written when the call ends).	Retry after a few seconds.