Skip to main content

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

​
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. Read the trunk record to decide:
  • 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:
  • 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.
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