Licence server: MonoPbx Voice billing error codes (LIC-VOICE-*)
Answered by the licence server's voice billing routes (/v1/voice/wallet, /v1/voice/topups, /v1/voice/bundles,
/v1/voice/usage, /v1/voice/snapshot) as application/problem+json (type, title, status, code), or raised
by the database. There is no pay as you go since the owner's decision of 2026-11-21: each pack (bundle) at most once per
company, calls only within the packs' minutes. Payment failures (402) also carry detail, decline_code and manage_url (the account page).
Internal guide: voice-billing.md; the catalogue and switch codes are in
licence-voice.md. Every route answers 503 LIC-VOICE-OFF while [voice] enabled = false.
| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
LIC-VOICE-COMPANY | 422 | every billing route | The company query parameter is not a company reference (1 to 64 letters, digits, _ . : -). Left out, it is default (a single-company install). | Send the PBX's company (tenant) reference, or leave it out. |
LIC-VOICE-NO-WALLET | 404 | GET /v1/voice/wallet, /snapshot, /usage, /bundles | MonoPbx Voice was never set up for this company of this install. | Create the wallet with PUT /v1/voice/wallet (or a first pack). |
LIC-VOICE-CURRENCY | 422 | wallet, bundle | The currency is not USD or MXN, or differs from the wallet's (a wallet's currency never changes). | Leave currency out, or send the wallet's currency. |
LIC-VOICE-SUSPENDED | 403 | bundle, POST /v1/voice/accounts, DID order | The operator suspended MonoPbx Voice for this company (vendor admin /admin/voice), or the anomaly detector stopped it (fraud hard stop). The snapshot answers suspended meanwhile. | Contact support. |
LIC-VOICE-NO-PAYG | 410 / 422 | POST /v1/voice/topups (410), PUT /v1/voice/wallet (422) | There is no pay as you go (owner 2026-11-21): no top-ups, no PAYG switch, no auto-recharge. payg_enabled: false (or leaving the PAYG fields out) is accepted. | Buy the packs the company needs (POST /v1/voice/bundles). |
LIC-VOICE-PACK-HELD | 409 | POST /v1/voice/bundles, PATCH /v1/voice/bundles/{id} | The company already holds this pack (a pending, active, past-due or cancelling subscription of it, or one that becomes it at its renewal). Each pack is bought at most once per company; different packs combine freely. Buying a pack that is cancelling (stops at period end) keeps it instead (200, no charge). Nothing was charged. | Use the subscription the company has; to change it, PATCH its interval, or remove it with DELETE. |
LIC-VOICE-PACK-QUANTITY | 422 | POST /v1/voice/bundles, PATCH /v1/voice/bundles/{id} | quantity is not 1: a pack is bought once (an older subscription of several units may only go down to 1). | Leave quantity out or send 1. |
LIC-VOICE-PRECONDITION | 428 | PUT /v1/voice/wallet | The wallet exists and the request has no If-Match. | Read the wallet and send its ETag in If-Match. |
LIC-VOICE-STALE | 412 | PUT /v1/voice/wallet | The wallet changed since it was read. | Read it again and repeat the change. |
LIC-VOICE-IDEMPOTENCY-KEY | 428 | POST /v1/voice/bundles, PATCH /v1/voice/bundles/{id} | The command has no (or an invalid) Idempotency-Key header (1 to 128 printable characters). | Send a fresh key per purchase and the same key on a retry. |
LIC-VOICE-INVALID | 422 | wallet, bundle, usage | A value is out of range: dates YYYY-MM-DD, limit 1 to 1,000, a cursor from the last answer. | Fix the request. |
LIC-VOICE-NO-CARD | 402 | bundle | The licence account has no card on file. | Add a card on the account page (manage_url), then retry with the same key. |
LIC-VOICE-PAYMENT-FAILED | 402 | bundle | The card was declined (decline_code when the bank gave one). Nothing was charged. | Use another card, then retry with a new key. |
LIC-VOICE-TOPUP-MIN, LIC-VOICE-LIMIT-DAY, LIC-VOICE-LIMIT-STARTING, LIC-VOICE-LIMIT-COUNT, LIC-VOICE-FROZEN, LIC-VOICE-METHOD | (retired) | POST /v1/voice/topups | Top-up refusals of the pay-as-you-go balance, retired on 2026-11-21 with it; never answered any more (the route answers 410 LIC-VOICE-NO-PAYG). | None. |
LIC-VOICE-BUNDLE-UNKNOWN | 422 | POST /v1/voice/bundles | The bundle does not exist, is not on sale, or has no price in the wallet's currency. | Pick a bundle from GET /v1/voice/catalogue. |
LIC-VOICE-SUBSCRIPTION-UNKNOWN | 404 | DELETE, PATCH /v1/voice/bundles/{id} | No such bundle subscription for this company. | Use an id from GET /v1/voice/bundles. |
LIC-VOICE-INTERVAL | 422 | POST /v1/voice/bundles, PATCH /v1/voice/bundles/{id} | interval is not month or year. | Use month or year. |
LIC-VOICE-CHANGE-PENDING | 409 | PATCH /v1/voice/bundles/{id} | A change of interval (monthly to annual or back) already waits for the next renewal; nothing else can change before it. | Wait for the renewal, then change again. |
LIC-VOICE-SUBSCRIPTION-NOT-ACTIVE | 409 | DELETE, PATCH /v1/voice/bundles/{id} | The subscription is not running (already ended or never paid). | Nothing to cancel. |
LIC-STRIPE-UNAVAILABLE | 502 | bundle | Stripe did not answer. Nothing is known to have been charged; a retry with the same Idempotency-Key never charges twice. | Retry later with the same key. |
LIC-VOICE-LEDGER-UNBALANCED | (database) | voice_ledger_postings | A ledger transaction's postings do not sum to zero; the transaction is refused at commit. Only a hand-written SQL change can cause it. | Never write the ledger by hand; there are no operator adjustments since 2026-11-21 (no balance to correct). |
LIC-VOICE-INSTALL-UNKNOWN | 404 | /v1/portal/voice/* | The install query parameter is missing, malformed, or not a server of the signed-in licence account (a trial, a licence, a live link or a wallet of it). | Use an install from GET /v1/portal/voice. |