Common error codes (mpbx-common)
Every mpbx_common::Error carries a stable code. The API layer maps the kind to an HTTP status and
uses the code as the RFC 9457 problem type suffix. Messages never contain secrets.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-INVALID-ARGUMENT | invalid_argument | A value is malformed, for example an ID that is not a UUIDv7. | Fix the request. |
MPBX-NOT-FOUND | not_found | The entity does not exist or is not visible in your tenant. | Check the ID and tenant. |
MPBX-CONFLICT | conflict | State conflict, including an optimistic-lock version mismatch. | Re-read and retry. |
MPBX-UNAUTHENTICATED | unauthenticated | No valid credentials. | Sign in again. |
MPBX-PERMISSION-DENIED | permission_denied | Authenticated but the role lacks the permission. | Ask an admin. |
MPBX-UNAVAILABLE | unavailable | A dependency (Postgres, Valkey, ClickHouse, object store) is down. Retryable. | Retry; check dependency health. |
MPBX-INTERNAL | internal | Unexpected condition. | Report with the log line. |
MPBX-CONFIG | config | Generic configuration problem. | Fix mpbx.toml or the environment. |
MPBX-SIP-DOMAIN-UNSET | config / unavailable | The install has no SIP domain (the digest realm phones register with). A SIP-role process refuses to start; an API pod answers 503 on routes that issue SIP credentials. | Set http.base_domain or sip.install_domains in a pod's configuration for its first start, or finish the setup wizard with an address ([setup] fqdn). It is stored once in the database and shared by every pod (setup-wizard.md). |
MPBX-CONFIG-INVALID | config | The merged configuration did not parse: unknown key, wrong type or bad address (including an [ice] URL with the wrong scheme, credentials or a bad transport, or ice.turn_ttl_secs outside 60..=86400). The message names the key. | Fix the named key; typos are errors on purpose. |
MPBX-CONFIG-FILE-NOT-FOUND | config | The config file named explicitly (path argument or MPBX_CONFIG) does not exist. | Fix the path. |
MPBX-CONFIG-MISSING | config | A required setting (for example postgres.url) is not set. The message names the env variable. Also: ice.turn_urls is set but the install secret TURN_SECRET is missing or shorter than 24 characters (nat-turn.md). | Set it in mpbx.toml or via the environment; for TURN, pass TURN_SECRET from mpbx init (never invent one). |
MPBX-CONFIG-UNKNOWN-FLAG | config | [features] names a flag that does not exist. | Check the spelling against the known flags. |
MPBX-TENANT-MISMATCH | permission_denied | The credential (token or API key) belongs to another company than the one the request addresses (host, X-Mpbx-Tenant header or a tenant id in the request). | Sign in on your company's address, or use a credential of that company. |
MPBX-TENANT-CLAIM-INVALID | unauthenticated | The token's tenant claims are inconsistent: tenant scope without tid, or system scope with a tid. | Sign in again; report it if it repeats (a token minting bug). |
MPBX-TENANT-SYSTEM-REQUIRED | permission_denied | An install-wide operation (companies, install settings, backups, upgrades) was called with a company-scoped credential. | Use a System Owner/Admin account. |
MPBX-TENANT-REQUIRED | permission_denied | A system-scope credential called a company operation without selecting the company. | Send the X-Mpbx-Tenant: <company id> header (the action is audited). |
MPBX-APIKEY-MALFORMED | unauthenticated | The API key is not in the mpbx_k1_<company>_<key id>_<secret> format. The key is never echoed. | Copy the whole key again, or create a new one. |