call_sid, so once you have that from your reports you can follow one call across signalling, media, and the agent. Pull the SIP ladder and the per-call quality numbers from the call trace explorer in the console before you start guessing.
This is the debugging reference. For the step-by-step for a trunk that won’t come up at all, see SIP Trunk Issues; for audio flowing only one way, One-Way Audio; for a call that never answers, Call Does Not Connect.
Where to look first
Get the call_sid
Find the call in your reports and copy its
call_sid. Every downstream tool — the SIP ladder, the media quality record, the CDR — is keyed on it.Read the SIP ladder
Open the call trace explorer and pull the full request/response ladder for that
call_sid. The final response code and the Reason / Q.850 cause on the last message tell you whether signalling or the far end failed.Read the media quality record
Every call that reached the media plane has a per-call quality record — packet loss, jitter, and an MOS score derived from them. If signalling looks clean but callers complain, this is where the answer is. See MOS, Jitter & Packet Loss.
Drop to packets only if needed
If the summary numbers don’t explain it, capture the raw SIP and RTP at the edge. See Packet-Level Debugging.
SIP signalling failures
The SIP gateway answers inbound calls as a back-to-back user agent (B2BUA), so it owns both legs of every dialog. A healthy inbound answer runs100 Trying → 183 Session Progress with SDP (early media) → 200 OK with the same SDP → ACK. Deviations from that sequence are the most common cause of “the call connected and then dropped.”
Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
INVITE gets no response at all | Source IP not matched to a trunk, or blocked by the source-IP ACL | Confirm the carrier’s signalling IP is on the trunk (trunks are matched by source IP or dialed DID). Check the ACL. See SIP Trunk Issues. |
INVITE answered 403 Forbidden | Trunk/ACL rejected the source, or the spam filter tripped | Verify the trunk’s internal_sip_ip / source IP and realm; review spam-filter thresholds. |
INVITE answered 404 Not Found | Dialed DID isn’t provisioned or isn’t bound to a trunk/agent | Import the E.164 number and bind it to a trunk and an agent. See Number Provisioning. |
488 Not Acceptable Here | Codec mismatch — the offered SDP had no codec the engine will answer | Offer G.711 µ-law (PT 0) or A-law (PT 8). The engine transcodes to its internal bus, but the wire codec must be one it accepts. See the Codec Guide. |
Call answers, then the carrier sends BYE within ~1 s | Provisional 180 Ringing sent without SDP, so no early-media path — some carriers tear down | The engine answers with 183 Session Progress carrying SDP for early media; make sure the carrier isn’t forcing an SDP-less 180. |
487 Request Terminated | Caller hung up (CANCEL) before answer — normal for abandoned calls | Usually benign. Correlate with ring duration in reports. |
408 Request Timeout / 480 Temporarily Unavailable | Far leg (human SIP phone, PSTN callee, or vendor) never responded | Check the destination endpoint’s registration and reachability; see registration section below. |
486 Busy Here / 603 Decline | Callee busy or declined | Expected; surfaces in the CDR as the mapped Q.850 cause. |
503 Service Unavailable | Upstream trunk or vendor congested / out of service | Retry over an alternate trunk; check carrier status. |
Call drops mid-conversation with BYE | Session timer / re-INVITE not honored, or media inactivity | Check for a stalled media path (see RTP section) — a dead media plane can trigger a teardown. |
Q.850 cause codes
When a call clears, the gateway writes a CDR that includes the Q.850 cause — the PSTN-world reason the call ended — mapped from the final SIP response. Read the cause on thecleared event to classify a hang-up without replaying the whole ladder. The common ones:
| Q.850 | Meaning | Typical SIP mapping | What it usually means |
|---|---|---|---|
| 16 | Normal call clearing | BYE / 200 | Either party hung up normally. |
| 17 | User busy | 486 Busy Here | Callee was on another call. |
| 18 | No user responding | 408 Request Timeout | Far leg never answered signalling. |
| 19 | No answer (user alerted) | 480 / 408 | Rang out with no pickup. |
| 21 | Call rejected | 403 / 603 | ACL, policy, or callee decline. |
| 27 | Destination out of order | 502 / 503 | Trunk or gateway down. |
| 31 | Normal, unspecified | 480 / 404 | Catch-all clearing. |
| 34 | No circuit/channel available | 503 | Trunk congestion / capacity. |
| 38 | Network out of order | 503 | Upstream network fault. |
| 41 | Temporary failure | 503 | Transient upstream error — safe to retry. |
| 47 | Resource unavailable | 503 | No media or signalling resource. |
| 88 | Incompatible destination | 488 | Codec / capability mismatch. |
| 102 | Recovery on timer expiry | 408 | A timer (e.g. session refresh) fired. |
| 127 | Interworking, unspecified | varies | Cross-network mapping loss. |
RTP / media failures
The media plane runs RTP/RTCP in-engine: G.711 on the wire (µ-law PT 0 / A-law PT 8), decoded to the runtime’s 8 kHz PCM16 bus, noise-suppressed, and re-paced back out every 20 ms (160 samples per tick). It scores each call’s quality from loss and jitter using an ITU-T G.107 E-model and writes an MOS estimate to the per-call quality record. DTMF rides as RFC 2833 events.Reading the RTP stats
Two numbers do most of the work:Derived from RTP sequence-number gaps. Sustained loss above ~1–2% is audible; above ~5% the call is rough. Bursty loss (dropped runs of sequence numbers) sounds worse than the same average spread evenly, because the jitter buffer can’t conceal a long gap.
Inter-arrival variation. The jitter buffer absorbs a working range; beyond it, late packets are discarded (and counted as loss) or introduce delay. Rising jitter with rising discard-loss is a network-path problem, not a codec problem.
Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
| Choppy / robotic audio, high loss % | Network loss on the RTP path, or bursty sequence gaps | Check the path to the carrier; loss is symmetric to jitter here. Capture RTP at the edge to see the gaps. See Packet-Level Debugging. |
| Audio delayed / “walkie-talkie” feel, high jitter | Jitter beyond the buffer’s working range → late packets discarded | Reduce path jitter; sustained high jitter shows as discard-loss and a low MOS. |
| One-way audio (caller can’t hear agent, or vice versa) | RTP flowing in only one direction — usually NAT/addressing: private bind IP advertised where a public IP is required | Confirm the trunk’s external_rtp_ip (public) vs internal_rtp_ip (bind). In cloud-NAT the SDP must advertise the public media address. See One-Way Audio. |
No audio at all, but call is established | SDP negotiated a codec the far end never sends, or media never opened | Verify the answered SDP codec matches the wire; confirm the call resolved to proxy media mode (the runtime requires proxied media for AI handling and recording). |
| DTMF digits not detected | Digits sent as in-band audio tones instead of RFC 2833 events | Configure the carrier/endpoint to send RFC 2833 (telephone-event) DTMF. |
| Pitch too high/low (“chipmunk”) | Sample-rate mismatch across a leg (e.g. an 8 kHz leg treated as 16 kHz) | This class of double-resample bug is fixed in the stateful resampler; if you see it on a bridged/vendor leg, check the leg’s declared clock rate. |
| MOS good but agent mishears speech | Not a transport problem — turn-taking or recognition | Move to the runtime side: Barge-In Debugging. |
Registration failures
The engine embeds its own SIP registrar (default-on, multidomain, digest auth + source-IP ACL, with nonce/replay hardening) — there is no separate registration server to run. Two kinds of party register: outbound trunks that register to a carrier, and human agents on real SIP deskphones/softphones that register to your workspace. Each workspace has its own SIP host,<workspace-id>.sip.telequick.dev, and the engine identifies the tenant from the leftmost DNS label of the inbound request.
Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
REGISTER challenged 401 Unauthorized in a loop | Wrong digest credentials, or the client isn’t re-sending with the Authorization header after the nonce challenge | Verify the AOR user and secret (secrets are sealed at rest). A single 401 challenge is normal — a loop means the credential response is wrong. |
REGISTER answered 403 Forbidden | Source IP not on the SIP ACL, or wrong realm/domain | Add the device’s IP to the SIP ACL and confirm it’s registering to the right <workspace-id>.sip.telequick.dev realm. |
REGISTER answered 404 / 488 | Registering to the wrong tenant subdomain, so the leftmost label doesn’t resolve to your workspace | Point the SIP client at <workspace-id>.sip.telequick.dev exactly; the label is the tenant key. |
| Phone registers, then goes unreachable after a minute or two | Registration Expires too short and the client isn’t refreshing | Ensure the client re-registers before expiry; the binding TTL follows the Expires value. |
| Inbound call to a registered phone never rings it | Contact bound to a private/NAT address the engine can’t reach | The engine binds on a private IP but must advertise a reachable Contact/Via; confirm public vs private addressing for cloud-NAT. |
| Trunk won’t register outbound to the carrier | Wrong sip_username / sip_password or register_expires_sec, or the carrier expects a specific transport (WS/WSS) | Check the trunk credentials and transport (sip_ws vs sip_wss/TLS). See SIP Trunk Issues. |
A quick triage flow
Did the call set up?
No final
200 OK in the ladder → signalling. Read the final response and Q.850 cause above. If the trunk never came up, go to SIP Trunk Issues.Did it set up but sound bad or go one-way?
Call is
established but audio is poor → media. Read loss/jitter/MOS; for one-way audio check RTP addressing. Go to One-Way Audio or MOS, Jitter & Packet Loss.Is it a device or trunk that won't come up?
REGISTER failing → registration. Check credentials, ACL, tenant subdomain, and expiry above.Still stuck?
Capture the raw packets at the edge and read the wire directly. Go to Packet-Level Debugging.
Related
SIP Trunk Issues
The focused runbook for a trunk that won’t register or route.
MOS, Jitter & Packet Loss
How to read the media quality metrics this page points you at.
Packet-Level Debugging
When the summaries aren’t enough, read the SIP and RTP off the wire.
Call Lifecycle
The healthy INVITE-to-CDR sequence these failures deviate from.