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.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-VOICE-UNAVAILABLE | unavailable | The 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-UNREACHABLE | unavailable | GET /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-INVALID | invalid | The 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.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
MPBX-VOICE-NOT-ENABLED | 404 | MonoPbx 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-INVALID | 400 | A 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-HELD | 409 | POST /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-FOUND | 404 | The 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):
| Reason | SIP | Meaning |
|---|---|---|
voice_bundle_exhausted | 403 | The company's pack minutes for this destination are used up (no overage: there is no pay as you go). |
voice_user_cap_reached | 403 | The user's minutes for this destination are used up. |
voice_destination_not_in_plan | 403 | No active pack of the company covers the destination, or it is a premium, high-risk or excluded destination. |
voice_balance_insufficient | 403 | Retired with pay as you go (2026-11-21); only in call history from before. |
voice_service_suspended | 403 | MonoPbx Voice is off or suspended for the company. |
voice_unavailable | 503 | The 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.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-VOICE-OFF | unavailable (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-ENTITLED | permission (403) | The licence in force does not include MonoPbx Voice (voice missing from its feature list). | Attach a licence that includes it. |
MPBX-VOICE-COUNTRY | invalid (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-ON | conflict (409) | MonoPbx Voice is not on for the company (sync, number orders). | POST /voice-service/enable first. |
MPBX-VOICE-MANAGED | conflict (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-LIVE | conflict (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-LICENCE | as answered | The 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-UNKNOWN | not found (404) | The number is not a MonoPbx Voice number of the company. | Check GET /numbers. |
MPBX-VOICE-ADDRESS-INVALID | invalid (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. |