> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting: voice agent dispatch eligibility

> Resolve VOICE_AGENT_MISSING, VOICE_AGENT_UNAVAILABLE, and VOICE_OPERATOR_LIMIT_EXCEEDED refusals when a voice queue cannot place an agent on a call.

# Troubleshooting: voice agent dispatch eligibility

A voice call that reaches an ACD queue can still fail to place an agent on the line. The operator-visible refusal falls into one of three codes, and each one points to a different layer of the dispatch gate. This page maps `VOICE_AGENT_MISSING`, `VOICE_AGENT_UNAVAILABLE`, and `VOICE_OPERATOR_LIMIT_EXCEEDED` to the control you own and the fastest path back to ringing agents.

These codes surface when the queue dispatcher has already accepted the call and is now trying to attach an agent. They are not destination blocks, call-quality failures, or handoff errors. Read the code first, then work the matching section below.

## Distinguish the three dispatch refusals

| Error code | What it means | Layer that failed |
| - | - | - |
| `VOICE_AGENT_MISSING` | No agent row exists for the target the queue resolved. | Identity / provisioning — the dispatcher looked up an agent id and found no row. |
| `VOICE_AGENT_UNAVAILABLE` | An agent row exists, but the membership does not pass the dispatch-eligibility gate. | Presence, aux-code state, queue membership, or skills mismatch. |
| `VOICE_OPERATOR_LIMIT_EXCEEDED` | The tenant's operator ceiling tripped on simultaneous join attempts. | Capacity — too many agents tried to join calls at the same time. |

`VOICE_AGENT_MISSING` is a data-lookup failure: the queue's routing logic nominated an agent id that is not present. `VOICE_AGENT_UNAVAILABLE` is an eligibility failure: the agent is real but is currently `busy`, `wrapup`, `paused`, `offline`, or not a member of the queue, or their skills do not cover the queue entry's requirements. `VOICE_OPERATOR_LIMIT_EXCEEDED` is a concurrency cap: the agent was eligible, but the tenant-wide simultaneous-operator ceiling rejected the join attempt.

## Diagnose per code

### `VOICE_AGENT_MISSING` — no agent row

1. **Find the agent id the queue resolved.** The refusal body includes the agent id the dispatcher tried to claim. Copy it before anything else.
2. **Check whether the id exists.** Open the agent in the dashboard (Voice → Agents, or `GET /api/v1/voice/agents/{id}`). If the id returns `404`, the row was deleted, the id was renamed, or the queue config is pointing at a stale reference.
3. **Trace where the id came from.** Queue membership lists, routing-rule fallback user ids, and supervisor reassignment targets can all nominate an agent id. The most common cause is a deleted agent left behind in one of those lists.
4. **Fix by removing or replacing the stale reference.** Either re-add the agent under a new id and update every membership, or remove the stale id from the queue / routing rule so dispatch no longer resolves it.

### `VOICE_AGENT_UNAVAILABLE` — agent row exists but membership does not pass the gate

1. **Read the agent's worst-case state across all queues.** Presence is stored per queue membership, and every dispatch reader folds memberships into one worst-case state by severity: `busy > wrapup > paused > offline > available`. An agent who is `available` on one queue but `paused` on another is treated as `paused` for voice claim purposes. See [Agent presence and aux-code lifecycle](/concepts/agent-presence-lifecycle).
2. **Check queue membership.** Confirm the agent is a member of the queue the call entered. `GET /api/v1/voice/queues/{id}/members` lists members; if the agent is absent, add them or fix the routing rule that sent the call to the wrong queue.
3. **Check the per-call skills filter.** The queue entry may carry `requiredSkills`. If the agent's `skillLevels` do not intersect, dispatch skips them even when they are `available`. Read the routing-decision audit (`GET /api/v1/inbox/routing-decisions/{conversationId}` or the queue decision log) to see the skills-filter reason.
4. **Check wrap-up and aux-code drift.** An agent stuck in `wrapup` after a call ended, or stuck in `paused` after a reason-code overrun, looks eligible in the directory but is not. Use `POST /api/v1/voice/agents/{id}/status` to force the correct state, or wait for the wrap-up timer / overrun scheduler to clear it.

### `VOICE_OPERATOR_LIMIT_EXCEEDED` — operator ceiling tripped

1. **Read the limit in the refusal.** The error body includes the ceiling value and the current count, for example `{ "limit": 50, "current": 50 }`.
2. **Distinguish a real spike from a leak.** A short spike during a campaign burst or a simultaneous shift change is expected. A count that stays pinned at the ceiling between calls suggests agents are not being released when calls end — check for stuck `busy` rows after hangup.
3. **Reduce concurrency or raise the ceiling.** Smooth the burst if the traffic pattern is the cause, or contact your account manager to raise the operator limit if the ceiling is structurally too low for your agent count.

## Fix — resolve presence, membership, and aux-code drift

The fastest recovery for `VOICE_AGENT_UNAVAILABLE` is usually a presence reset:

1. Open the agent in the dashboard or call `GET /api/v1/voice/agents/{id}`.
2. Verify the state you see matches the state the queue dispatch reads. If it does not, the in-memory registry and the audit table have drifted — the registry wins for live routing, but the dashboard may lag until the next write-through succeeds.
3. If the agent is stuck in `paused`, resume them with `POST /api/v1/voice/agents/{id}/status` → `available`. If they are stuck in `wrapup`, either submit a disposition or wait for `acd_queues.wrap_up_seconds` to expire.
4. Re-check queue membership and skills. Add the agent to the queue if missing, or align `requiredSkills` / `minSkillLevel` so the agent qualifies.
5. Retry the call or wait for the next dispatcher tick. Voice queue dispatch runs on a periodic scan, so a state fix can take one tick to reflect.

For `VOICE_AGENT_MISSING`, the fix is provisioning hygiene: remove stale ids from queue memberships and routing rules. For `VOICE_OPERATOR_LIMIT_EXCEEDED`, the fix is capacity management: release stuck agents or raise the ceiling.

## What to capture before escalating

If the checks above do not clear the code, open a ticket with:

1. **The full error body** — code, message, and the `details` object (agent id, limit, current count, queue id).
2. **The call id and queue id** from the call detail view or the voice gateway log.
3. **The agent id** the dispatcher tried to claim.
4. **The agent's current state** as shown in the dashboard and as returned by `GET /api/v1/voice/agents/{id}`.
5. **Your organization ID** (Settings → Organization, or `organizationId` from `GET /api/v1/me`).

## What not to do

* **Do not retry the call blindly.** `VOICE_AGENT_MISSING` and `VOICE_AGENT_UNAVAILABLE` repeat until the underlying agent record or state changes.
* **Do not assume one queue's state overrides another.** Dispatch takes the worst state across memberships; fixing one queue does not clear a `paused` row on another.
* **Do not treat `VOICE_OPERATOR_LIMIT_EXCEEDED` as a queue-specific problem.** The ceiling is tenant-scoped, not per-queue.
* **Do not change the call destination to work around the refusal.** The destination already reached the queue; the issue is agent placement.

## See also

* [Agent presence and aux-code lifecycle](/concepts/agent-presence-lifecycle) — the five-state machine dispatch checks before it rings.
* [The ACD queue model](/concepts/acd-queue-model) — how queue entries, FIFO dispatch, skills filtering, and overflow interact.
* [Troubleshooting: in-call AI handoff, deflection, and follow-up failures](/troubleshooting/voice-ai-handoff-deflect-followup) — for `HANDOFF_FAILED`, `DEFLECTION_FAILED`, and `FOLLOWUP_SEND_FAILED` after an AI agent tries to transfer.
* [Troubleshooting: voice destination and emergency blocks](/troubleshooting/voice-destination-blocks) — for pre-flight destination blocks such as `VOICE_DNO_BLOCKED` and `VOICE_COUNTRY_RATE_LIMITED`.
* [References: error codes](/reference/error-codes) — the platform-wide error catalog.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.