Skip to main content

​
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

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

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

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

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:
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

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.
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