Call control error codes (mpbx-api call-control routes, mpbx-b2bua control)
Returned by the Call Control REST API (W7-API-01, /api/v1/call-control/...) and by the engine
methods behind it (B2bua::call_view, calls_view, hangup, hold, answer, send_dtmf).
Transfer and park pass the transfer codes of transfers.md through; originate passes
the MPBX-CALL-* codes of calls.md through. Messages never contain numbers, names,
digits or SIP identifiers. Guide: Call Control REST API.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
MPBX-CC-CALL-NOT-FOUND | 404 | No live call with this id that you may control: it ended, it is another company's call, or none of its parties is in a department where you hold calls:control (all look the same). | List the calls (GET /call-control/calls); the call may have ended. |
MPBX-CC-PARTICIPANT-NOT-FOUND | 404 | The participant is not a live party of the call, not one of the two talking parties (hold, DTMF), or the device does not ring for the call (answer). | Read the call's participants again; use a participant_id from them. |
MPBX-CC-STATE | 409 | The call is not in a state the action applies to: not answered (hold, DTMF), not ringing (answer), on hold by the other party, in a transfer, a park, an app, a queue or a conference, a call the PBX placed that is not connected yet, held by the phone itself (resume), or already ending (drop). | Wait for the call to reach the state, or act on the phone. |
MPBX-CC-FORBIDDEN | 403 | Never through the API: an emergency call is not hung up, held, transferred, parked or sent digits. | Nothing: emergency calls are handled on the phone. |
MPBX-CC-UNSUPPORTED | 503 | The engine cannot do it now: no media app for music on hold, the media service refused, the parties could not be bridged again (the call stays on hold), the device could not be asked to answer, or the other side refused the digits. | Check [media] and the media service; retry. |
MPBX-CC-INVALID-DTMF | 400 | The digits are not 1 to 32 of 0-9, *, #, A-D. | Send only valid DTMF. |
MPBX-CC-USER-OUT-OF-REACH | 403 | Originate for a user you may not control, or name a party of a live call (transfer, park, hold, resume, DTMF) who is a person outside your reach: your calls:control covers none of the user's departments. | Use a key or a role with calls:control for the user's department, or company-wide. |
MPBX-CC-STREAM-TOO-MANY | 429 | Media stream (W9-AI-06): too many open streams for this API key or user (4), this company (100), or this call already has one. | Close a stream first; retry after Retry-After. |
MPBX-CC-STREAM-BAD-FRAME | (WebSocket error event) | A media stream text frame is not a known command, or an audio frame is malformed (header, track 0, even PCM length, at most one second). The stream stays open. | Follow the frame format in the media stream guide. |
MPBX-CC-STREAM-PLAYBACK-FULL | (WebSocket error event) | More than 10 s of audio is queued for playback. The frame was dropped. | Send a mark and wait for it before sending more audio, or clear. |
MPBX-CC-STREAM-UPGRADE-REQUIRED | 426 | A plain HTTP request reached GET /call-control/calls/{id}/media-stream. | Connect with a WebSocket client. |
MPBX-CC-STREAM-CREDENTIAL-ENDED | (close 4401) | While streaming, the credential expired or was revoked, or lost calls:control. | Reconnect with a valid credential. |
Also: MPBX-RBAC-FORBIDDEN (403) without calls:control; MPBX-CALL-ENGINE-UNAVAILABLE (503)
on an API node without the call engine; MPBX-RATE-LIMITED (429, api.md) beyond 10
originated calls a minute per API key or user (and per target user) or 60 call-control requests a
minute per API key or user.
Audit
Every record has result (ok or the error code) and the outcome denied for a refusal:
call.control_originate (destination, device_id, call_id; the entity is the user),
call.control_drop, call.control_answer (device_id), call.control_hold,
call.control_resume, call.control_transfer (participant_id, destination or
voicemail_extension), call.control_park (participant_id, orbit) and call.control_dtmf
(participant_id, digit_count: never the digits).
Media stream (W9-AI-06): call.control_media_stream_open (rate, tracks, stream_id; also
when refused, for an emergency call) and call.control_media_stream_close (stream_id,
reason, duration_s, frames_out, frames_in, commands); commands on the stream are
audited as their REST routes. Audio and digits are never recorded.