Licence server: MonoPbx Voice error codes (LIC-VOICE-*)
Answered by the licence server's voice routes as application/problem+json (type, title, status, code), or
recorded on switch jobs and catalogue changes. Design: cloud-offering.md; internal guide:
voice-switch-adapter.md. Texts never carry switch credentials or SIP passwords.
| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
LIC-VOICE-OFF | 503 | GET /v1/voice/catalogue | MonoPbx Voice is not turned on at this licence server ([voice] enabled = false, the default). | The PBX keeps its last catalogue and offers no voice bundles. Operators turn the feature on in the licence server configuration. |
LIC-VOICE-PREMIUM-IN-BUNDLE | (database) | catalogue rows | A change would let a bundle cover a premium-rate or high-risk prefix (cat_voice_excluded_prefixes). The transaction is refused at commit; the message names the group, the reason and the prefix. | Add an exclude row for the prefix to the group in the same transaction, or keep the group out of every bundle. |
LIC-VOICE-SWITCH-NOT-CONFIGURED | (job) | voice_jobs.last_error | The switch adapter cannot make the call: the http adapter before the owner's switch API is mapped. The job is parked as failed. | Use switch_mode = "fake" until the http adapter ships; requeue the job afterwards. |
LIC-VOICE-SWITCH-UNAVAILABLE | (job) | voice_jobs.last_error | The switch did not answer (connection error, timeout, 429, 5xx). The job is retried with backoff (30 s doubling to 1 h) up to voice.job_max_attempts. | Nothing; check the switch if jobs keep failing. |
LIC-VOICE-SWITCH-REFUSED | (job) | voice_jobs.last_error | The switch refused the call (invalid request, empty rate deck, unknown job kind). Not retried. | Read the stored text; fix the data or the configuration and requeue. |
LIC-VOICE-SWITCH-NOT-FOUND | (job) | voice_jobs.last_error | The account, number, order or port does not exist at the switch. Not retried. | Check the reference against the switch. |
Voice accounts and numbers
Answered by /v1/voice/accounts[/{company}/...] (install-signed, for the licence account the install is linked to).
Guide: voice-accounts-dids.md.
| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
LIC-VOICE-ACCOUNT-UNKNOWN | 404 | every /v1/voice/accounts/{company}/... route | MonoPbx Voice is not on for this company of this install (or another licence account owns it). | Turn MonoPbx Voice on first (POST /v1/voice/accounts). |
LIC-VOICE-ACCOUNT-NOT-READY | 409 | POST .../dids/orders | The voice account has no switch account yet (the switch was unavailable when voice was turned on). | Turn MonoPbx Voice on again (the call is idempotent). |
LIC-VOICE-COUNTRY | 422 | POST /v1/voice/accounts, search, orders | The country (or a number's country) is not in voice.did_countries (phase 1: US, MX, CO). | Choose a supported country. |
LIC-VOICE-INVALID | 422 | every voice route | A field is missing or malformed (company reference, auth mode, public IP list, delivery key, numbers, cursor). | Fix the request; the title names the field. |
LIC-VOICE-IDEMPOTENCY-KEY | 400 | POST .../dids/orders | The order has no Idempotency-Key. | Send one; a repeat with the same key answers the same order. |
LIC-VOICE-KYC-MISSING | 422 | POST .../dids/orders | A document the country requires (switch did_requirements) is not among the uploaded documents named in the order. | Upload it (POST .../documents) and order again. |
LIC-VOICE-KYC-INVALID | 422 | POST .../documents | Not a PDF, JPEG or PNG, or the bytes do not match the type. | Upload the scan as PDF, JPEG or PNG. |
LIC-VOICE-KYC-OFF | 503 | POST .../documents | No at-rest key (MPBX_LICENSE_ESIM_SECRET_KEY or voice.kyc_key_file): documents cannot be kept sealed. | Operators set the at-rest key. |
LIC-VOICE-DID-LIMIT | 409 | POST .../dids/orders | The wallet would hold more than [voice.billing] max_dids_first_month (5) numbers in its starting period (plan Q9). | Wait until the starting period ends, or ask the operator to approve the wallet. |
LIC-VOICE-DID-TAKEN | 409 | POST .../dids/orders | A number of the order is already held by an account (one live row per number). | Search again. |
LIC-VOICE-DID-UNKNOWN | 404 | release, emergency address | The number is not a live number of this account. | Check the number. |
LIC-VOICE-DID-BUSY | 409 | DELETE .../dids/{e164} | The number is not active yet (its order is still running). | Release it when the order is done. |
LIC-VOICE-ORDER-UNKNOWN | 404 | GET .../dids/orders/{id} | No such order for this account. | Check the id. |
LIC-VOICE-DIDS-LIVE | 409 | DELETE /v1/voice/accounts/{company} | The company still has numbers that are ordered, waiting for an address or active, or a port request that is still open, so its voice account cannot be closed. Released numbers in their 30-day hold do not count. | Release the numbers (or wait for the port request to finish), then turn MonoPbx Voice off again. |
LIC-VOICE-PORT-LOA | 422 | POST .../ports | A port request needs the signed letter of authorisation among its documents (an uploaded document of kind loa). | Upload the LOA (POST .../documents, kind loa) and send the request again. |
LIC-VOICE-PORT-TAKEN | 409 | POST .../ports | A number of the request is already a MonoPbx Voice number of an account, or in another open port request. | Leave that number out, or wait for the other request to finish. |
LIC-VOICE-PORT-NOT-CANCELLABLE | 409 | POST .../ports/{id}/cancel | The port request can no longer be cancelled: it has finished (completed, rejected or cancelled), a cancellation is already under way, or the confirmed port date is less than two days away. | Nothing to do; a completed port's numbers can be released like any number. |
LIC-VOICE-PORT-UNKNOWN | 404 | GET .../ports/{id}, POST .../ports/{id}/cancel | No such port request for this company. | Check the id. |
LIC-VOICE-ADDRESS-INVALID | 422 | orders, PUT .../emergency-address | The emergency address is incomplete or invalid (US: two-letter state and a 5 or 5+4 digit ZIP; a US number needs a US address). | Correct the address. |
LIC-VOICE-SWITCH-* | 503 / 422 / 404 | account creation, search, orders | The switch did not answer, refused or does not know the object (same codes as the switch jobs above). Answers keep the safe text only. | Retry later; an account stays pending and the next turn-on completes it. |