> ## 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: SIP trunk down or calls failing

> Diagnose a failing SIP trunk — check registration status, read the recorded error, walk the failover chain, and interpret route-quality and auth-attempt signals.

# Troubleshooting: SIP trunk down or calls failing

A trunk that cannot register, or one that keeps completing fewer calls than
you expect, shows up in three places: the **SIP settings** table in the
dashboard, the registration diagnostic stored on the trunk itself, and the
route-quality view. This page works through the checks in order, then covers
what the platform does on its own when a trunk stops answering.

## Check the trunk's registration status

Each trunk carries a cached registration verdict — `registered`,
`unregistered`, or `unknown` — with the ISO timestamp of the last check. The
cached verdict feeds the dispatch gate: a trunk whose registration check
stays stale or failing stops being offered new calls.

Confirm the current state either way:

* **Dashboard**: open **Settings → SIP trunks**; the table marks
  unregistered trunks and shows the last recorded registration error
  inline per row.
* **API**:

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

Or query every trunk ranked with the ones needing attention first:

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

Read the recorded registration error on the trunk first — most
`unregistered` rows are one of four causes: DNS failing to resolve the
host, a firewall blocking the SIP port, a digest username/password
mismatch, or codec/TLS mismatch on the REGISTER handshake.

The platform re-checks each enabled trunk on a cadence of about five
minutes, running a real SIP REGISTER with the trunk's stored credentials
and persisting the verdict back onto the trunk row. To force a fresh check
after you change something, run the trunk's own test from the dashboard
("Test trunk") or:

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

A still-failing check returns the step that failed — DNS resolution,
TCP/TLS connect, or the REGISTER itself — and records it on the trunk.

## Common causes and how to fix them

| Cause                                         | How to confirm                                                                                                            | What to do                                                                                                                                                        |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Carrier credentials wrong**                 | The recorded registration error names digest authentication; last check timestamp updates but status stays `unregistered` | Update the username/password on the trunk and retest; rotate credentials from the trunk's settings if the carrier side changed them                               |
| **Firewall or ACL blocks the SIP port**       | The probe fails at the connect step, not at REGISTER                                                                      | Verify your carrier's SIP host and port (5060/5061); allow the platform edge IPs on your carrier side for inbound trunks                                          |
| **Codec mismatch**                            | Registration succeeds but calls fail at the media stage                                                                   | Ensure your carrier supports OPUS, PCMU (G.711 µ-law), and PCMA (G.711 A-law) — the codecs Orbit negotiates — and enable at least one of them on the carrier side |
| **Trunk disabled or cap reached**             | Trunk is `enabled: false`, or route-quality shows its concurrency cap saturating at the same time calls were lost         | Re-enable the trunk, raise its concurrent-call cap, or spread traffic across additional trunks                                                                    |
| **IP allowlist too narrow (incoming trunks)** | Auth attempts appear in the incoming-trunk auth log but never turn into registered calls                                  | Add every carrier SBC/source IP to the trunk's allowlist, or switch the trunk's auth mode to digest if the carrier deaggregates outbound IPs                      |

## What happens when a trunk fails

A failed trunk does not take its calls down with it.

* When the primary trunk's cached registration status is anything other
  than `registered`, the dispatch path walks the trunk's failover chain —
  the backup trunk(s) you designate in the dashboard's trunk settings —
  picking the first healthy candidate. The chain is guarded against loops
  and hops are bounded, so a miswired chain cannot recurse on itself.
* When no usable failover exists — or none is configured — outbound calls
  still terminate: they land on the Devotel wholesale softswitch, the
  platform's default outbound path, exactly as they would with no trunk
  configured at all.
* Across your outbound trunk pool, keep capacity and quality spread: each
  trunk's route-quality view scores its answer ratio (ACR) and capacity
  utilization and flags a saturated cap as blocked rather than failed, so
  you can tell "carrier is dropping the route" apart from "the trunk is
  full."

Query the per-trunk route-quality snapshot:

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

The window accepts `24h` or `7d`. Use the ranking to spot the trunk that
should be taken out of rotation while you fix it.

## Inbound trunk signals: the auth ledger

For incoming trunks — where your carrier originates calls toward the
platform — each failed digest or allowlist attempt is recorded against the
trunk for seven days. That is the first place to check when inbound calls
stop arriving but the trunk row looks healthy: a burst of source IPs you
have not allowlisted, a digest realm that never matches because the
password rotated, or an `ip_allowlist`-only trunk queried from a carrier
SBC whose egress IP changed.

Read the ledger via the trunk detail surface in the dashboard, or:

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

## When to escalate

If you worked through the list, the trunk still shows `unregistered`, and
the recorded error text has stopped matching anything on this page, open a
support ticket with the trunk ID (`trunk_…`), the recorded registration
error string from the row, and the timestamp of the last successful
registration if the trunk previously registered.

For calls that register and connect but sound wrong — one-way audio, dead
air, choppy audio, or long post-dial delay — see
[Troubleshooting: voice call quality](/troubleshooting/voice-call-quality).