> ## 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: call fails right after a regional failover or failback

> Diagnose a call that fails on the first attempt after the media plane hands off to another network region, or hands back — tell a handoff-time failure from a BYOC trunk-path failure, then work the checklist.

# Troubleshooting: call fails right after a regional failover or failback

The complaint is specific: a call fails **once**, right after a media-plane
region handoff — either a failover (your traffic moved to a backup region) or
a failback (it moved back to the primary) — and every retry after that
succeeds. From the dashboard that looks like a random one-off "call failed,"
so it is easy to dismiss. This page isolates the two failure shapes it can be,
then gives a checklist that pins whichever one it is.

A region handoff touches two independent things: **where the media runs** (the
region the call's media plane terminates in) and **which SIP trunk carries the
call** (your BYOC trunk or Orbit's default outbound routing). They fail
differently, so the first step is deciding which layer broke.

<Note>
  Orbit does not silently move a call to another region — cross-region
  failover is opt-in by design, never automatic, and a pinned region cannot be
  silently substituted
  (see [Multi-region media routing](/concepts/media-region-routing)).
  A "handoff" here means a deliberate move: a failover you opted into, or a
  failback after one. Failovers on tenants that pinned a region intentionally
  refuse to happen at all — which is itself one of the failure shapes below.
</Note>

## Handoff-time failure vs BYOC trunk-path failure

Work this fork first; the two branches go to different pages.

**A handoff-time failure** is specific to the window: the first call after the
move fails, the same call retried moments later succeeds, and nothing else in
your trunk health looks wrong. That signature usually means the call hit a
stale target — the media plane re-resolved its region, but the dial path read
an older trunk verdict, an empty failover chain, or a region preference that
no longer matches where calls land.

**A BYOC trunk-path failure** is not site- or window-specific: the same class
of call keeps failing after the handoff, and the trunk record shows a real SIP
problem — a registration flap, a 401/488, a TLS handshake error. That is not
the region handoff; it is the trunk, and it is covered by
[Troubleshooting: SIP trunk registration, health, and failover](/troubleshooting/sip-trunk).

Read the trunk record to decide:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/<trunk_id>" \
  -H "X-API-Key: $ORBIT_API_KEY"
```

* If `lastRegistrationError` names a SIP step (`401`, `488`, `TCP/TLS
  connect`, `DNS resolution`) or `registrationFailureCount` is non-zero, treat
  it as a trunk problem and work the SIP trunk page.
* If the trunk reads `registered` with a clean failure streak, the failure was
  at the handoff window — work the checklist below.

## Checklist

Work these in order; each one eliminates a handoff-window cause.

### 1. Verify the preferred-region mapping

A handoff that resolved to the wrong region often comes from the workspace
preference, not the trunk. Read what the region is set to and where it
currently resolves:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/regions/preferred" \
  -H "X-API-Key: $ORBIT_API_KEY"
```

* `preferred: "auto"` means the region is chosen per call — a failover between
  regions is expected, and the handoff window is normal to have a first-call
  risk.
* An explicit `preferred` value (`eu` / `us`) pins every new call to that
  region. If the failing call tried to run in a different region than
  `preferred`, that mismatch is the finding — align the preference with where
  you actually want the media, or clear it back to `auto` if you do not need a
  residency pin.

Changing the preference affects **new** calls only; calls already placed keep
the region they started in.

### 2. Confirm the trunk still sends to the right region

For BYOC (bring-your-own-carrier) trunks, the failover target is a region as
well as a trunk. If the primary trunk registered to a region that no longer
serves your calls, the backup candidate is skipped and the dispatch falls to
either the next chain candidate or the default outbound route.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/health" \
  -H "X-API-Key: $ORBIT_API_KEY"
```

Check the failover target's row, not just the primary's. A target must be
enabled **and** `registered` for dispatch to pick it; a target sitting at
`degraded` or `down` is skipped exactly as if it were unconfigured. If the
failover event "never kicked in," that is why — the chain read a target that
was not usable.

### 3. Confirm failback caps did not gate the return

Failback after a failover is bounded deliberately, so a chain does not flap
between trunks. The dispatch path limits how many hops it walks and how often
it re-evaluates the chain. If the failback "never happened" or the return leg
failed once and recovered, the cause is usually one of these:

* **The chain is cycle-checked at save time and hop-bounded at dispatch** —
  a cycle or an over-long chain means the dispatch could not walk back to the
  primary. Re-save the failover chain and retest.
* **The primary was not re-checked yet** — after the failback trigger, the
  primary is only re-read once its next health probe lands. A failback that
  fired on a stale verdict fails the first attempt and succeeds on retry.
  Force a fresh probe (`POST /api/v1/voice/sip-trunks/:id/test`) instead of
  waiting for the cadence, then re-attempt the call.

### 4. If the trunk path is clean, escalate with the handoff window

When the trunk record is clean, the region preference is aligned, and the
failback checks above come back clean, the residual handoff-window failure is
a platform-side signal, not something tenant config can fix. Do not keep
re-dialing as a fix attempt — capture the window below and escalate.

## When to escalate

Open a support ticket when the call fails at handoff time with all four above
checked. Include all of these so we can pull the exact attempt without a
back-and-forth:

1. **Your organization ID** (Settings → Organization, or `organizationId` from
   `GET /api/v1/me`).
2. **The trunk ID** (`trunk_…`) and the trunk-health row you read.
3. **The handoff window in UTC** — when the failover or failback fired, and
   when the failing call attempted.
4. **The last SIP response code or failed step** from
   `lastRegistrationError` (for a trunk-path case), or the full
   `GET /voice/regions/preferred` payload (for a handoff-time case).

## What not to do

* **Do not assume it is a trunk flap.** A first-call failure at handoff that
  recovers on retry is a region-resolution signal, not a SIP problem. Read
  `lastRegistrationError` before treating it as one.
* **Do not re-save the failover chain mid-event.** Dispatch reads the chain
  per call; editing it while the failback is in progress makes already-routed
  and newly-routed calls disagree about which trunk was the target.
* **Do not clear a residency pin to "test" failback.** A workspace pinned to a
  region intentionally rejects the cross-region move. If failback looks like
  it "never engaged," check whether your pin is the reason before touching
  the preference.
* **Do not redial as a probe.** A retry that succeeds tells you the handoff
  window closed — it does not tell you which of the four checks above was out
  of line.

## See also

* [Multi-region media routing](/concepts/media-region-routing) — how the
  region gets picked at room/call creation and why cross-region failover is
  opt-in.
* [Voice Data Residency & Retention](/compliance/voice-data-residency) —
  the region-preference controls (`auto` vs an explicit pin) and what the
  in-region guarantee covers.
* [Troubleshooting: SIP trunk registration, health, and failover](/troubleshooting/sip-trunk)
  — the SIP-layer branch for true trunk-path failures after a handoff.
* [Media planes](/concepts/media-planes) — which plane (SFU vs. Jambonz
  bridge) carries your media, independent of region.