AI error codes (mpbx-ai)
Raised by the LLM provider layer and the AI settings routes under /api/v1/ai (W9-AI-01, W9-AI-03,
W9-AI-11). Messages never contain an API key, a prompt or a provider's error message; they name the
provider kind, the HTTP status and the provider's error type at most. Guide:
AI providers and settings.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
MPBX-AI-FEATURE-DISABLED | 403 | The feature is switched off for the company or queue (the default). No provider was called. | Switch it on in Admin > AI. |
MPBX-AI-NO-PROVIDER | 500 | The feature is on but no enabled provider with a key is selected. | Add a provider with a key and select it. |
MPBX-AI-MODEL-UNKNOWN | 400 | The model is not in the catalog for Claude providers, or not a valid model name for an OpenAI-compatible endpoint, or the provider kind has no default model. | Choose a catalog model, or name one. |
MPBX-AI-PROVIDER-UNAVAILABLE | 503 | Every candidate (model fallbacks, fallback provider) timed out, could not be reached, answered 5xx / overloaded, or a stream broke off. | Retry later; add a fallback provider. |
MPBX-AI-RATE-LIMITED | 503 | The provider refused for its rate limit (429). | Raise the limit with your provider or add a fallback provider. |
MPBX-AI-AUTH-FAILED | 500 | The provider refused the key (401 / 403). | Enter a valid key. |
MPBX-AI-BAD-REQUEST | 400 | The provider refused the request as malformed, or the key / URL cannot be sent. | Report it; check the model name. |
MPBX-AI-BAD-RESPONSE | 503 | The provider's answer could not be read (not JSON, a tool call whose arguments are not an object, an event over 1 MiB, an answer over 4 MiB). | Check that the endpoint really speaks the chosen protocol. |
MPBX-AI-ENDPOINT-BLOCKED | 400 | The base URL is not public https (private, loopback or link-local address, internal name, plain http, credentials in the URL). | Use the provider's public https address. |
MPBX-AI-CATALOG-INVALID | - | The catalog file (MPBX_AI_CATALOG_FILE) is malformed or older than the built-in one; it was ignored (logged at start). | Fix the file or remove the variable. |
MPBX-AI-UNSUPPORTED-AUDIO | 400 | The speech provider cannot take this audio format, encoding or channel layout (for example mu-law for Azure's REST endpoint, or an output rate it does not offer). | Transcode to 16-bit PCM or pick a supported format. |
MPBX-AI-NOT-FOUND | 404 | No such AI provider (or queue override) in this company; another company's provider is invisible. | Check the id. |
MPBX-AI-FEATURE-UNKNOWN | 404 | Unknown feature name in the path. | Use voice_agent, live_assist, call_summary, voicemail_summary, call_analysis or transcription. |
MPBX-AI-TOO-MANY | 409 | The company already has 10 AI providers. | Remove one. |
MPBX-AI-IN-USE | 409 | Reserved: a provider still selected by a feature (today removal is allowed and the feature is left without a provider). | - |
MPBX-AI-AGENT-CONFIG-INVALID | 400 | The voice agent configuration cannot be used (no language or voice, a turn limit outside 0.5-30 s, menu keys other than 0-9 * #), or the company requires the AI consent announcement and the agent has none. The agent does not start; the call continues with the flow's next step. | Fix the agent configuration. |
MPBX-AI-AGENT-TIMEOUT | - | Logged when the voice agent did not start answering a caller turn within its hard limit (turn_timeout, default 3 s); the caller was transferred to a human (fallback reason turn_timeout). | Check the providers' latency; add a fallback provider. |
MPBX-AI-AGENT-DISABLED | 403 | The configured AI agent is switched off (its own switch; the company's voice_agent switch is MPBX-AI-FEATURE-DISABLED). A call flow's ai_agent node takes its error exit. | Switch the agent on in Admin > AI agents. |
MPBX-AI-ASSIST-SESSION-REQUIRED | 403 | Live assist is for signed-in users (an agent on a call); an API key has none. | Use a signed-in session. |