> ## 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: VOICE_GATEWAY_ERROR (502) at call-send > Classify a 502 VOICE_GATEWAY_ERROR from the voice gateway across the three operation lanes that emit it — outbound dispatch, voicemail-greeting synthesis, and mid-call actions — decide transient vs deterministic, retry safely, and capture the right support bundle. # 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](/reference/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](/troubleshooting/media-planes-failover-or-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: ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/health" \ -H "X-API-Key: $ORBIT_API_KEY" ``` 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](/troubleshooting/sip-trunk) 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](/troubleshooting/voice-destination-blocks). * **`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](/reference/error-codes) — the code table this page is the runbook for, and the retry-class matrix on it. * [Failover and failback](/troubleshooting/media-planes-failover-or-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](/troubleshooting/sip-trunk) — the trunk-layer branch: cached verdicts, probe results, and the fallback tags dispatch stamps onto the trunk detail page. * [Voice call quality](/troubleshooting/voice-call-quality) — for calls the gateway DID place: one-way audio, dead air, and jitter are a different layer once the dispatch succeeded.