Troubleshooting your Trunk

SIP Trunking Alerts

Twilio will log an Alert record when it encounters an error whilst making SIP requests to/from your SIP infrastructure. These may be very useful for debugging purposes. You can configure Alert Triggers to fire based on your preferences on any Alert error code; optionally, you can also send a corresponding webhook or an email notification. SIP specific error codes are in the 32xxx series.

Expert Services

Twilio Expert Services includes pre-packaged workshops, review and optimization services, and custom consulting engagements to help with best practices and technical integrations. Expert Services helps you reduce time to value and minimize risk. Go here if you wish to purchase Expert Services.

Common problems and solutions

Below you can find some common issues you might encounter when configuring your Elastic SIP Trunk. We provide an explanation of potential causes and some troubleshooting tips.

Remember that you can practice making a call and check that your communications infrastructure was properly configured with your Twilio Trunk, see Test your Trunk.

Termination calls (Your PBX/SBC to the PSTN)

Origination calls (from PSTN to your PBX/SBC)

One way audio issues

Termination calls (Your PBX/SBC to the PSTN)

You are not getting any response to your SIP requests

Cause: Your firewall is blocking the outbound SIP requests to Twilio.

Cause: Your PBX cannot access a DNS server on the public internet.

  • We will push the Termination URI that you specified on your trunk to public DNS servers. You either need to configure a local DNS server to resolve this URI or allow your PBX access to public DNS servers.

Cause: You are not putting the Termination URI in the Request-URI on INVITE requests that you send to Twilio.

  • If your request URI doesn’t reference the Termination URI you configured on your trunk, we will view your SIP messages as malicious and drop them. The Request-URI you send us needs to be sip:<e.164 formatted phone number>@<your termination URI>

You are getting 403 Forbidden responses to your INVITE requests

Cause: There is an ACL on your trunk and you are sending us INVITE requests from an IP address not on that ACL.

  • Check the received parameter on the Via header of the 403 response that we send you: it will tell you the IP address from which we are receiving your SIP request. Either fix local routing so that you are sending us SIP from an address already in your ACL or add this other address to your ACL

Cause: There is a Credentials List on your trunk, and your INVITE’s Authentication Digest is incorrect due to wrong username/password

  • Confirm that your username/password matches one in your Credentials List. A test is to remove the Credentials List and see if the call works with just an ACL.

Tip: You can tell which cause it is by which INVITE is getting the 403. If it is the initial, "digest-less" INVITE, the problem is most likely the ACL not matching. If it is the INVITE with an Auth digest (after a 407 Authentication required), the problem is most likely the credentials not matching.

The call fails with a 400 Invalid Phone Number error

Cause: When sending calls out through Twilio, you need to give us the dialed number in E.164 format.

  • Update the configuration on your PBX so that it puts the dialed number in E.164 format

The call fails with a ‘403 Invalid Caller ID’ error

Cause: Free Trial accounts are required to use a Twilio-validated Caller-ID.

  • Be sure to format the From number in full E.164 format, including the + sign. For example, +15005551212. It cannot be 5005551212, 15005551212.

  • Be sure to set the From number to either a Twilio number, or a verified Caller-ID number, in your Twilio account.

  • If a Remote-Party-ID is included in the INVITE, be sure it is also set to a valid Caller-ID, as described above.

The call fails with a ‘403 Phone number is blacklisted for verification’ error

Cause: The destination number is blacklisted by Twilio

  • Contact Twilio Customer Support at help@twilio.com if you have not knowingly blocked this number.

The call fails with a ‘403 No International Authorization’ error

Cause: You are attempting to make a call to a country that has not been enabled under your account’s Voice Geographic Permissions

The call fails with a `503 Trunk CPS limit exceeded’ error

Cause: You are generating Termination calls at a rate greater than the CPS that is set for your account; by default this is 1 Call Per Second.

  • You can increase your CPS rate for a fee; contact your Twilio Account Manager or Sales for more details.

  • Alternatively, reduce the rate at which your SIP Infrastructure queues up Termination calls to Twilio

The call fails with a `503 Trunk concurrent call limit exceeded’ error

Cause: You are using a Trunk on a Twilio Trial Account, and you have more than 4 concurrent active calls.

  • You can remove this restriction by upgrading to a Paid Account.

  • Alternatively, reduce the number of concurrent calls on your Twilio Trunk.

The call connects, there is two-way audio, but the call drops after 20 or 30 seconds

Cause: You SIP communications infrastructure is incorrectly Sending an ACK to Twilio using an IP address other than the Contact header's IP address found in Twilio's 200 OK in the Request-URI. This causes Twilio to not process the ACK, so the transaction times out after 30 seconds, and the call is torn down via a BYE sent from Twilio's side to both sides of the call.

  • Your SIP communications infrastructure should use the IP address in the Contact header of Twilio's 200 OK in the Request-URI of the ACK, and send the ACK to the IP address in the Record-Route header of the same 200 OK.

Cause: Your SIP communications infrastructure is incorrectly adjusting/replacing the Twilio Private IP addresses in the URI and headers of the ACK they return with their own Public IP addresses. This is causing Twilio to route the ACK back to the SIP communications infrastructure, and as such not process it. Because the ACK is not processed, Twilio (correctly) times out and tears down the call.

  • Your SIP communications infrastructure should never replace any of Twilio's own IP addresses; they should only adjust their own IP addresses.

Origination calls (from PSTN to your PBX/SBC)

On Origination calls (from PSTN to your PBX): there is no audio and the call drops after 20 or 30 seconds

Cause: Your SIP infrastructure is replacing a Twilio-specific private IP address in a stacked Via header with a different IP address in a 200 OK. This is likely due to a Global replacement of certain private IP ranges. This will cause the 200 OK to be dropped inside Twilio's infrastructure, preventing an ACK from being sent, and causing your infrastructure to terminate the call.

  • Your SIP infrastructure should not change the IP addresses in the Via headers when responding to an INVITE from Twilio.

On Origination calls (from PSTN to your PBX): there is two-way audio, but the call drops after 20 or 30 seconds

Cause: Your SIP infrastructure is returning a 200 OK with a Contact header which contains a Private IP Address. As Twilio is required to send the ACK back to the IP Address in the Contact header, the ACK is being sent out to that Private IP Address. Since Private IP Addresses are not publicly routable, the ACK never reaches your SIP Infrastructure, so the call times out on that end and is torn down.

  • Your SIP infrastructure should use Publicly Routable IP addresses in the Contact header when responding to an INVITE from Twilio.

On Origination calls (from PSTN to your PBX): The call is being rejected by the PBX with a ‘401 Unauthorized’ Error, or are reaching the PBX, but timing out with no response

Cause: Your PBX does not have the Twilio SIP Trunking IP addresses configured as Peers.

  • Update the configuration on your PBX so that the Twilio SIP Trunking signaling IP addresses for each applicable region are Trusted Peers. Addresses are per our IP address whitelist.

The call is being rejected by the PBX with a ‘407 Proxy Authentication Required’ Error

Cause: Your PBX does not have the Twilio SIP Trunking IP addresses configured/whitelisted as Peers.

  • Update the configuration on your PBX so that the Twilio SIP Trunking signaling IP addresses for each applicable region are Trusted Peers. Addresses are per our IP address whitelist.

The call is reaching the PBX, but timing out with no response

Cause: Your PBX does not have the Twilio SIP Trunking IP addresses configured/whitelisted as Peers.

  • Update the configuration on your PBX so that the Twilio SIP Trunking signaling IP addresses for each applicable region are Trusted Peers. Addresses are per our IP address whitelist.

The call fails with a ‘408 Request Timeout’ error or ‘504 Request Timeout’ error

Cause: Twilio is getting no response from your SIP infrastructure

  • Confirm that the SIP URI you have configured for your Trunk’s Origination settings is correct.

  • Check your firewall to be sure the Twilio IP addresses and ports are whitelisted

  • Check your PBX to be sure the Twilio IP addresses and ports are whitelisted

The call fails with a ‘422 Session Timer Too Small’ error

Cause: The customer’s PBX is set up with a Session-Expires value which is larger than what is in the INVITE. Possible issues are:

  • The customer's PBX has a very large Session-Expires value configured.

  • The Carrier INVITE has a very small Session-Expires configured.

Twilio does not support Session-Timers at this time, so we remove the Supported: Timer header. As such, the Session-Expires value really should be ignored by the PBX, but many do not do so. As a workaround, you should lower your PBX Session-Expires value to something reasonable like the usual defaults of 1800 or 3600.

The call does not reach your PBX, and does not show up in your Twilio Call-Logs

Cause: Your have either not configured an Origination SIP URI for your Twilio SIP Trunk, or have configured a “bad” SIP URI that does not resolve

  • Confirm that you have configured a valid, routable SIP URI for Origination.

Your call fails with a '415 Unsupported media type' error

Cause: Your SIP infrastructure does not list G.711 PCMU in its supported Codecs. Twilio currently supports only G.711 PCMU.

  • Make sure your SIP infrastructure supports G.711 PCMU.

On Origination calls (from PSTN to your PBX): The INVITE is reaching the PBX, but timing out with no response, and the INVITE is not showing in the PBX logs

Cause: Your firewall does not have the Twilio SIP Trunking IP addresses whitelisted.

  • Update the configuration on your firewall so that the Twilio SIP Trunking signaling IP addresses for each applicable region are whitelisted. Addresses are per our IP address whitelist.

One way audio issues

The person out on the PSTN can hear the person on your PBX but not vice versa

Cause: Your PBX is putting it’s LAN IP address into the SDP it sends to Twilio

  • Update the configuration on your PBX so that it puts its WAN IP address in the SDP

Cause: Your firewall is blocking RTP packets from Twilio

The person on your PBX can hear the person on the PSTN end of the call, but not vice-versa

Cause: Your firewall is blocking RTP packets from your PBX to Twilio

  • Update your firewall to allow/pass RTP from your PBX IP addresses and ports

Cause: Your Internet Provider is blocking RTP packets from your PBX to Twilio

  • Contact your Internet Provider to have them allow/pass RTP from your PBX IP addresses and ports

Cause: Your RTP packets are taking a route that reduces the TTL on the packets to a value too low to make it through Twilio’s infrastructure (10 or less).