SIP troubleshooting guide

The following sections cover some of the common issues and solutions for LiveKit SIP integrations.

General issues

The following issues can apply to both incoming and outgoing calls.

403 Forbidden

This error indicates an authentication or permission errors, but can also be returned when regional requirements are not met (see 403 - Domestic Anchored Terms Not Met).

Solution

Verify the username and password you're using are correct. Check the credentials you configured with your SIP trunking provider and confirm they match the credentials you set on the SIP trunk.

403 - Domestic Anchored Terms Not Met

This error commonly occurs in regions where regulations require calls to remain within national borders. If a call is routed to another country, SIP providers return this error to indicate that the call violates domestic compliance requirements.

Solution

Use region pinning to restrict calls to a specific region. For inbound calls, use region-based endpoints. For outbound calls, specify the destination_country parameter when you create an outbound trunk.

To learn more see SIP cloud and region pinning.

404 - Not Found

This error can be returned for multiple reasons. This section covers some of the possible 404 errors that can occur.

Solution

Depending on the error, check one or all of the following list:

• Confirm the LiveKit SIP trunk exists and the trunk ID is correct.
• Verify the destination number is a valid phone number.

Audio quality issues

Poor audio quality is often caused by network issues. If connectivity isn't the problem, other factors—such as background noise or echo picked up by the speaker—can affect audio quality.

Solution

Enable background noise cancellation (BVC) for your agent, along with client-side echo cancellation. Both are recommended for the optimal audio quality. To learn more, see Noise cancellation.

Call transfer issues

These errors can occur while trying to transfer a call using the TransferSIPParticipant API.

408 - Request Timeout

This Twirp error occurs if the transfer is rejected by the remote endpoint and the system times out waiting for a successful response.

Solution

To troubleshoot, try the following steps:

1. Verify the SIP URI for the transfer destination. Check that the URI is properly formatted and reachable.

2. Verify the trunk you configured with your SIP trunking provider. Check that it has the appropriate permissions to transfer calls to the target destination.

   Note

   If you're using Telnyx as your SIP provider, SIP REFER must be enabled for your account. If they've enabled it, but you're still unable to transfer calls, verify you can transfer calls outside of LiveKit using their API.

Inbound calls

The following issues are specific to inbound calls.

Call rings, but agent doesn't answer

This usually happens when the agent name is missing or incorrect in the dispatch rule. To ensure an agent answer incoming calls, you must explicitly set the agent name for the agent, and in the dispatch rule.

Solution

Make sure the agent name matches in both of the following places:

• When creating your agent: set agent_name for AgentServer. To learn more, see Explicit agent dispatch.
• When creating your dispatch rule: set agent_name in RoomAgentDispatch. For an example, see Caller dispatch rule (individual).

To learn more, see Agent dispatch.

Outbound calls

The following issues are specific to outbound calls.

503 - Service Unavailable

This error from your SIP trunking provider might be the result of a configuration issue with the address field for your outbound trunk.

For example, the SIP endpoint for Telnyx is sip.telnyx.com. If you include a subdomain in the address field (for example, myproject.sip.telnyx.com), this error occurs.

Solution

Check with your SIP trunking provider and verify you're using the correct SIP endpoint in the address field for your outbound trunk. To learn more, see Create an outbound trunk.

Cross referencing calls with Call IDs

Understanding how different IDs relate to a call helps with debugging and support requests:

• SIP Call ID: Generated by the SIP protocol, unique for every SIP session.
• Call ID (SCL_xyz): LiveKit's identifier for the call.
• Provider ID: Unique ID generated by the remote provider (like Twilio, for example, CAxyz). This ID is passed to LiveKit using SIP X headers.

Working with PCAPs

Packet Capture (PCAP) files contain network traffic data that can help diagnose SIP and RTP issues. You can use Wireshark to analyze PCAPs.

The following sections describe how to identify the INVITE flow, codec negotiation, and visualize RTP flow in a PCAP file. To learn more about the data in a PCAP file, see SIP primer.

Identify the INVITE flow

1. Open the PCAP file in Wireshark.
2. Use the display filter for SIP traffic: Type in sip in the display filter text field.
3. Look for the initial INVITE from the caller to the callee.

Follow the SIP transaction:

INVITE → 100 Trying → 180 Ringing / 183 Session Progress → 200 OK → ACK

To learn more, see SIP handshake.

Identifying the codec negotiation

1. Look inside the SDP portion of the INVITE and 200 OK:
   • Examine the SIP / SDP sections of the packet.
   • Find the m=audio line listing payload types.
   • Look for a=rtpmap to see which payload type corresponds to which codec (for example, 0 PCMU/8000).
2. Determine the chosen codec:
   • The caller's INVITE lists all supported codecs.
   • The callee's 200 OK lists acceptable codecs, with the first listed codec being the codec that is used.

To learn more, see Audio codecs negotiation.

Visualize RTP in and out

1. Open the PCAP file in Wireshark.
2. Select Statistics → I/O Graphs.
3. Select the plus (+) icon to add a new graph to visualize incoming RTP traffic:
   • For Graph Name, enter "In"
   • For Display Filter, enter rtp && ip.dst_host matches "^10."
   • For Y Axis, select Packets.
4. Add a new graph to visualize outgoing RTP traffic:
   • For Graph Name, enter "Out"
   • For Display Filter, enter rtp && !(ip.dst_host matches "^10.")
   • For Y Axis, select Packets.

Additional resources

For SIP errors not covered in this topic, see List of SIP response codes.