> ## 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: MCID flag failures

> Resolve MCID_INVALID_DIRECTION, MCID_CALL_TOO_OLD, and the 404 on the malicious-call trace (/ *57) flag endpoint — map each reject to the call's direction, age, or lookup scope.

# Troubleshooting: MCID flag failures

Malicious Call Identification (MCID) — the classic PSTN call-trace service,
dialed as `*57` in NANP regions — flags an **inbound** call so the carrier
preserves the originating caller's identity for law-enforcement or abuse-team
handoff. Use it on a threatening, harassing, or nuisance call, or on one where
the caller spoofed or withheld their display name.

Flagging is deliberately narrow. Two eligibility gates guard it:

* **Inbound only.** A callee reports an inbound nuisance caller — an outbound
  call you placed is never eligible.
* **Recent only.** The flag must land within **7 days** of the call, because
  the carrier-side trace data that makes MCID actionable ages out.

This page maps each flag-reject code to the gate that fired and the fix you
own, then covers the export role gate and the dashboard flow.

## Code matrix — which gate fired

| Error code | HTTP | Fired on | Go to |
| - | - | - | - |
| `MCID_INVALID_DIRECTION` | 400 | Flag attempted on an outbound call | [Outbound call rejected](#mcid-invalid-direction) |
| `MCID_CALL_TOO_OLD` | 409 | Flag attempted after the 7-day window closed | [Aged-out call rejected](#mcid-call-too-old) |
| `NOT_FOUND` | 404 | The call ID is not in your tenant's call log | [Unknown call ID](#not-found) |
| role gate | 403 | Export attempted by a non-owner/admin role | [Export is owner/admin only](#export-role-gate) |

```bash theme={null}
# Flag a call
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/mcid/{callId}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Caller made threats"}'

# Read current flag state
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/mcid/{callId}" \
  -H "Authorization: Bearer $API_KEY"
```

A successful flag returns 201 with the trace record, including the audit-chain
anchor for the report. Re-flagging a call that is already flagged returns 200
with the existing record, so repeat clicks are safe.

## Outbound call rejected — MCID\_INVALID\_DIRECTION<a id="mcid-invalid-direction" />

`400 MCID_INVALID_DIRECTION` fires when the flag targets a call whose
direction is outbound. MCID reports an inbound caller; flagging a call your
tenant placed has no carrier-trace meaning, so the endpoint refuses it before
writing anything.

Fix it upstream — never let the flag control appear on an outbound call:

1. Filter the call list to `direction: "inbound"` before rendering the
   **Flag** action on a call or recording detail view.
2. If your integration builds its own flag UI, hide or disable the action when
   the call record's direction is not inbound instead of posting and handling
   the 400.

## Aged-out call rejected — MCID\_CALL\_TOO\_OLD<a id="mcid-call-too-old" />

`409 MCID_CALL_TOO_OLD` fires when the call's start time is older than the
7-day eligibility window. The carrier-side CDR and SIP signaling trail that an
abuse team needs to action a trap-trace degrades with age, so the window is a
hard gate, not a warning.

Fix it in the client and set the operator's expectation:

1. Surface "This call is too old to trace — report it to your carrier directly."
2. Disable the **Flag** action client-side when the call's `startedAt` is more
   than 7 days in the past; re-enable it for calls inside the window.
3. Coach agents to flag promptly — the 7-day bound exists to keep reports
   actionable, and a nuisance call flagged same-day carries the strongest
   trace data.

## Unknown call ID — NOT\_FOUND<a id="not-found" />

`404 NOT_FOUND` means the call ID you posted is not in your tenant's call log.
Common causes:

* The ID came from a different tenant's log or a stale cached list — re-list
  your own calls and flag from the fresh response.
* The call never reached your tenant (for example, a call you saw on the
  carrier's own portal, not in Orbit).

Confirm the call exists before offering the flag:

```bash theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/mcid/{callId}" \
  -H "Authorization: Bearer $API_KEY"
```

A 404 on the state read tells you the flag will also 404 — drop the action
from the UI for that row.

## Export is owner/admin only<a id="export-role-gate" />

`GET /api/v1/voice/mcid/export` produces the regulated report — every flagged
call in a date range, for law-enforcement or abuse-team handoff. Because it
surfaces preserved caller identity across potentially many calls, only the
**owner** and **admin** roles may call it. An agent or developer token
receives `403`.

```bash theme={null}
# Export all flagged calls (owner or admin role required)
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/mcid/export?from=2026-09-01&to=2026-09-30&limit=200" \
  -H "Authorization: Bearer $API_KEY"
```

Query parameters: `from` and `to` (ISO dates, default the last 90 days) and
`limit` (1–500, default 200). If your agent needs the export, have an
owner/admin run it — do not bypass the gate by elevating an agent token.

## Dashboard flow — how a flag normally lands

1. Open the call or recording detail page for an **inbound** call inside the
   7-day window.
2. Choose **Flag for malicious-call trace** and optionally add a reason (up to
   500 characters).
3. The flag writes an immutable record to your audit log under the
   `voice_mcid.flagged` action — the record is tamper-evident and independent
   of later dashboard edits, which is what makes it usable in a
   law-enforcement handoff.
4. An owner/admin exports the report when an abuse team or carrier asks for it.

## What not to do

* **Do not retry a 400 or 409.** Both are deterministic eligibility gates;
  the same request never succeeds later (a 409 only worsens as the call
  ages). Fix the call selection, not the request.
* **Do not flag outbound calls** expecting the carrier to trace them — the
  reject is doing what the service promises.
* **Do not share the export broadly.** It carries preserved caller identity
  for a regulated purpose; keep it in the owner/admin lane it is gated to.

## See also

* [Get mcid / Create mcid / Export](/api-reference/endpoints/voice) — the
  endpoint contract this page triages against.
* [References: error codes](/reference/error-codes) — the error catalog.
* [Troubleshooting: voice call park orbit](/troubleshooting/voice-call-park) —
  the sibling code-matrix runbook for the park surface.