Skip to main content

MonoPbx Voice error codes (mpbx-voice-plan, mpbx-activation voice catalogue)

Raised by the PBX's MonoPbx Voice bundle engine. They appear in the engine's logs (mpbx::voice_plan); a call that meets one is refused with the dial plan reason shown, never with the code itself. Guide: MonoPbx Voice bundle engine.

CodeKindMeaningWhat to do
MPBX-VOICE-UNAVAILABLEunavailableThe usage counters (Valkey) did not answer. Pack calls route on the last snapshot's minutes without a reservation; with no minutes left there they are refused (voice_bundle_exhausted).Check Valkey; the counters resync with the next snapshot.
MPBX-VOICE-CATALOGUE-UNREACHABLEunavailableGET /v1/voice/catalogue on the licence server failed (network, TLS, non-2xx). The catalogue in use stays; with none loaded since start every managed call is refused (voice_unavailable). Retried every minute.Check outbound HTTPS to the licence server ([license] server_url).
MPBX-VOICE-CATALOGUE-INVALIDinvalidThe licence server answered with something that is no catalogue (not JSON, no version, over 16 MB). The catalogue in use stays.Report it to MonoPbx support with the time.

Console and API​

Returned by Admin > Plan & usage (/api/v1/voice-plan*) as problem+json (the numbers routes are below). A payment the bank refuses is not an error of the pack routes: they answer 200 with the result card declined. There is no pay as you go (owner 2026-11-21): no top-up route and no overflow setting. Codes of the licence server (LIC-VOICE-*, and MPBX-LIC-NOT-LINKED when this server is not signed in to a licence account) pass through.

CodeHTTPMeaningWhat to do
MPBX-VOICE-NOT-ENABLED404MonoPbx Voice is not turned on on this server ([features] voice_plan), so the Plan & usage routes do not exist.Turn MonoPbx Voice on, or ignore: the console hides the pages.
MPBX-VOICE-INVALID400A field is refused: warning share outside 1 to 99, more than 10 or malformed alert addresses, a cap outside 0 to 1,000,000 minutes, an interval other than monthly / annual, a pack key that is not one of the catalogue. (overflow and quantity are unknown fields since 2026-11-21: 400.)Correct the field named in errors.
MPBX-VOICE-PACK-HELD409POST /voice-plan/bundles: the company already has this pack. Each pack is bought at most once per company; different packs combine freely. Nothing was charged. A pack that stops at the end of its period is kept instead (no charge).Use the pack the company has; remove it to stop it at the end of its period.
MPBX-VOICE-USER-NOT-FOUND404The user is not in this company, or has no cap to remove.Reload the list.

Call refusal reasons​

Not error codes but the dial plan's reasons (X-Mpbx-Reject, call history, SIP events cause):

ReasonSIPMeaning
voice_bundle_exhausted403The company's pack minutes for this destination are used up (no overage: there is no pay as you go).
voice_user_cap_reached403The user's minutes for this destination are used up.
voice_destination_not_in_plan403No active pack of the company covers the destination, or it is a premium, high-risk or excluded destination.
voice_balance_insufficient403Retired with pay as you go (2026-11-21); only in call history from before.
voice_service_suspended403MonoPbx Voice is off or suspended for the company.
voice_unavailable503The catalogue, the snapshot or the counters are unavailable (fail-closed).

MonoPhone and the web dialer show each reason as its own sentence ending with "Ask your administrator" (app.callreject.voice_*, web.callreject.voice_*).

Voice accounts, numbers and emergency​

Answered as application/problem+json by the telephony API (/voice-service, /numbers, /emergency-addresses, and the trunk, outbound-rule and emergency-number routes for what MonoPbx Voice keeps). Guide: voice-accounts-dids.md.

CodeKindMeaningWhat to do
MPBX-VOICE-OFFunavailable (503)MonoPbx Voice accounts are off on this install ([features] voice_accounts = false, the default, or no licence server).Operators turn the feature on; until then the voice routes answer this.
MPBX-VOICE-NOT-ENTITLEDpermission (403)The licence in force does not include MonoPbx Voice (voice missing from its feature list).Attach a licence that includes it.
MPBX-VOICE-COUNTRYinvalid (422)MonoPbx Voice is sold for companies in the US, Mexico and Colombia; no supported country was given or set for the company.Send country (US, MX, CO) or set the company's country.
MPBX-VOICE-NOT-ONconflict (409)MonoPbx Voice is not on for the company (sync, number orders).POST /voice-service/enable first.
MPBX-VOICE-MANAGEDconflict (409)The trunk, outbound rule or emergency number is kept by MonoPbx Voice: only the trunk's name, enable switch and caller-ID presentation can change, and nothing it keeps can be deleted one by one.Turn MonoPbx Voice off to remove them; add rules of your own beside them.
MPBX-VOICE-NUMBERS-LIVEconflict (409)POST /voice-service/disable while the company has numbers that are ordered, waiting for an address or active, or (at the licence server) a request to bring numbers that is still open. Nothing is removed.Release the numbers first (DELETE /numbers/{e164}) or wait for the port request to finish.
MPBX-VOICE-LICENCEas answeredThe licence server refused a voice call or did not answer; the detail starts with its LIC-VOICE-* code (see licence-voice.md), the status follows it (404, 409, 422, 503).Act on the LIC-VOICE-* code.
MPBX-VOICE-NUMBER-UNKNOWNnot found (404)The number is not a MonoPbx Voice number of the company.Check GET /numbers.
MPBX-VOICE-ADDRESS-INVALIDinvalid (422)The emergency address is incomplete or invalid (US: two-letter state, 5 or 5+4 digit ZIP; a US number needs a US address).Correct the address.