Skip to main content

​
Troubleshooting: queue emergency activation 422 EMERGENCY_DESTINATION_REQUIRED

Queue emergency mode is the supervisor panic button: while armed, every new inbound call to the queue routes straight to the emergency destination instead of the agent matcher. Arming it requires a destination. If the queue has none stored and the request supplies none, the activation is refused:
  • error.code — always EMERGENCY_DESTINATION_REQUIRED, HTTP 422, on POST /api/v1/voice/queues/{id}/emergency with active: true.
  • details.queueId — the queue the activation targeted.
The refusal is a validation error, not an outage: nothing changed, and the queue keeps routing normally.

​
Why the API refuses

Arming a queue with no destination would leave it in an “emergency mode” state that silently routes calls normally. The override would read as active to your supervisors while changing nothing for callers, which is exactly the state you cannot afford to trust mid-incident. The 422 enforces a configure-then-activate order instead: a destination must exist, either stored on the queue or supplied with the activation, before the toggle can succeed.

​
Fix: configure, then activate

​
Step 1. Store the destination on the queue

The field takes an E.164 number. Storing it does not arm the queue; it only records where calls go once the switch is flipped. You can also set the same field at queue creation.

​
Step 2. Arm the override

With a destination stored, this succeeds and the response carries the updated queue config. Alternatively, arm and set the target in one request:
destination in the toggle body overwrites the stored value; omit it to arm with the stored one.
Arming or disarming is a supervisor, admin, or owner action. A caller without one of those roles receives a 403 before the destination check runs.

​
Read the current posture

The queue config object returned by the queue read and by every write on this page carries both fields:
  • emergencyActive — true while the override is armed, false otherwise.
  • emergencyDestinationNumber — the stored E.164 destination, or null when none is configured.
Read the queue with GET /api/v1/voice/queues/{id} and confirm both before you rely on the override in an incident. While armed, every new inbound call to the queue routes straight to the destination. The routing layer re-reads the posture on each inbound call, so an arm or disarm takes effect at the next call. Callers already waiting in the queue keep their place and are served by the agent matcher as usual.

​
Adjacent safety gates are independent

Two nearby gates look related but neither reads nor writes the queue’s emergency fields:
  • Callback dispatcher emergency-dial block. The virtual-callback dispatcher never dials emergency short codes (see the queue SLA forecast callback gate runbook). That guard applies to callbacks the platform places, not to the destination your queue forwards inbound calls to.
  • Platform emergency-calling block. Outbound dials of 911 / 112 and the other emergency short codes are refused platform-wide with EMERGENCY_CALLING_NOT_SUPPORTED (see Emergency calling). Queue emergency mode reroutes inbound calls only; it never places an outbound emergency call, so arming it cannot trip that block.
If your error body says EMERGENCY_CALLING_NOT_SUPPORTED, you are on the outbound-dial page, not this one.

​
Deactivate and fail back

active: false restores normal ACD routing for new inbound calls at the next call; the stored destination stays in place for the next activation. To clear the stored destination as well, send destination: null in the same request, or set "emergencyDestinationNumber": null on the queue PUT. Clearing the destination also disarms the override, so a queue can never hold an armed state with no target.

​
What to send support

If the 422 persists after you store a destination:
  • the queueId from error.details,
  • the request_id from the response envelope,
  • the queue config read showing emergencyActive and emergencyDestinationNumber,
  • the request sequence you sent (queue PUT, then the emergency toggle).
With those, support can separate a configuration race from a role or payload problem on your side.