Skip to main content

​
Troubleshooting: VOICE_GATEWAY_ERROR (502) at call-send

VOICE_GATEWAY_ERROR is the API’s refusal code when the voice gateway — the Jambonz / SBC layer that turns your API call into a call on the wire — never answered the request. The call never reached the wire: no ringing, and a dispatch that fails here is never billed. The error arrives as HTTP 502 or 503 with code: "VOICE_GATEWAY_ERROR" in the standard error envelope (see Error codes), and none of it means your payload was wrong — the request was accepted and the gateway underneath failed or was unreachable. This page separates the transient shapes you can safely retry from the trunk-config shape you cannot, on each of the three operations that raise this code.

​
The three operation lanes

Read the HTTP method and path of the failed request first — it tells you which lane you are in before anything else. 1. Outbound dispatch — POST /api/v1/voice/calls. The API handed the call to the voice gateway and the gateway answered with an error, or never answered within the dispatch timeout. A reconnect into the gateway is retried for you on the transient classes; VOICE_GATEWAY_ERROR is what surfaces when every attempt still failed. The cold-start shape (503 with a “temporarily unavailable” message right after a platform rollout) lives here too. 2. Voicemail-greeting synthesis and upload — POST /api/v1/voice/voicemail/greetings (and its resubmit attempts). A 502 here means either the text-to-speech provider refused or returned empty audio, or the rendered audio could not be pushed to storage. Both are raised before any greeting row is written — the error response is the whole outcome, nothing partially landed. 3. Mid-call actions — park, flip, transfer, and conference mutations on a live call. The call stood up fine, but the follow-up control command to the gateway failed — the far-end action (park, flip) never happened while the call itself is usually still up. Verify the action actually landed before treating the call as re-arranged.

​
First check — gateway side or trunk side

A 502 from dispatch sits on top of one of two layers: the gateway being genuinely down or cold (platform side), or your BYOC trunk being unreachable behind it (config side). Work the two existing runbooks by lane, instead of re-probing blindly:
  • Gateway side — if several dispatches fail close together or the error clustered right after a regional move, read the regional handoff first: failover and failback. A first-call failure at the handoff window that succeeds on retry is a handoff-window signal, not a trunk problem.
  • Trunk side — dispatch reads the SIP trunk’s cached registration verdict before every call. Check your trunk rows:
A trunk at unregistered, degraded, or with a non-zero registrationFailureCount makes the gateway-side dispatch fail on the trunk leg — work SIP trunk registration, health, and failover for that layer. In lane 1 the dispatch falls back through your failover chain or the platform default instead of refusing, so a trunk problem shows up here as a 502 only when nothing in the chain could take the call.
  • Lane 2 (greetings) — the gateway here is the synthesis provider plus storage, not your trunk. If every greeting attempt 502s while calls dispatch fine, the trunk records will not explain it; capture the request-id and escalate (below).

​
Retry-safety

VOICE_GATEWAY_ERROR is the transient class: the platform caught a 5xx-or-transport failure and no deterministic verdict was reached. All three lanes are safe to re-issue — the operation is idempotent on this failure: no call leg was created, no greeting row was partially written, and the mid-call action either landed or did not (the error is raised only when it did not). What differs is only HOW you re-issue:
  • Honor retry_after when the envelope carries it. A 429-triaged or backpressured gateway may return details.retry_after (seconds); wait that long before the next attempt — do not hammer a cooling lane.
  • Use spaced retries otherwise. Two retries at growing gaps beat immediate re-issues: a cold-start window (the 90–120 s after a platform rollout) and a handoff window both close on their own.
  • A retry that succeeds on the second attempt is the expected transient signature — the gateway or trunk layer recovered, nothing to fix.
  • A retry that fails deterministically every time is no longer a gateway error in disguise — the layer underneath is telling you the call cannot route at all, and you are in the trunk-side branch of the check above.

​
What this code is NOT

Two sibling voice codes fail at a completely different layer — read the code, not just the 502/503 status, before you treat a dispatch refusal as a gateway failure:
  • VOICE_DNO_BLOCKED (422) — the destination number sits on a Do-Not-Originate list, and the call was refused BEFORE the gateway was ever asked. No retry will fix it; the destination is deliberately unreachable. See suspect voice destination.
  • VOICE_CALLER_ID_REJECTED — the trunk refused your FROM identity (the caller-id was not in the trunk’s allowed list nor an org-owned DID). Also deterministic and also pre-gateway: fix the caller-id or the trunk identity configuration, do not retry.
Both of those are tenant-config problems masquerading as dispatch failures — neither involves the gateway answering with an error, and neither clears by waiting.

​
When to capture and escalate

Escalate once the transient window has honestly closed — after your retries span the cold-start window above, the trunk-health check reads clean, and the same code keeps returning on the same lane. Capture the bundle BEFORE the retry storm so support can pull the single failing attempt without a back-and-forth:
  1. request_id — from the error envelope’s meta.request_id. This is the one field that lets support pull the exact gateway attempt.
  2. call_sid — from the response or the call-log row, when dispatch got far enough to mint one. For mid-call actions this is the live call’s SID; for lane 1 failures it may be absent (no call ever started).
  3. Timestamp in UTC — when the 502 landed, and how long the streak ran.
  4. The lane and operation — dispatch vs greeting vs mid-call action, and the endpoint you called.
Do not keep re-issuing as a fix attempt beyond a few backoff-spaced retries on the same lane — a deterministic 502 stays deterministic, and each repeat only moves the same failure further into the log window.

​
See also

  • Error codes — the code table this page is the runbook for, and the retry-class matrix on it.
  • Failover and failback — the first-call-after-handoff window, and how to read the trunk record to decide gateway-side vs trunk-side.
  • SIP trunk registration, health, and failover — the trunk-layer branch: cached verdicts, probe results, and the fallback tags dispatch stamps onto the trunk detail page.
  • Voice call quality — for calls the gateway DID place: one-way audio, dead air, and jitter are a different layer once the dispatch succeeded.