Our support team will often ask you for a "SIP Trace" (or 'pcap') in order to help diagnose any issues you're having.
These traces are simple text files (or a simple text file can be created from the pcap) but are not intended to be human-readable and are often confusing. A "pcap" is a full packet capture, and provides a lot more information than a simple SIP trace, so is preferred where possible - especially if you have an issue with call audio.
The ultimate authority on SIP is the specification RFC 3261, but below we'll take a look at an example call and the corresponding SIP trace, together with some common errors you might see, to help you debug your SIP calls.
There are a few common messages you'll see in most calls, some with simple text names e.g;
And some numeric codes, followed by a human-readable description;
- 100 Trying
- 180 Session Progress
- 183 Ringing
- 200 OK
If you're familiar with HTTP, you'll recognise some of these numbers, they have (mostly) the same meaning in SIP as in HTTP.
The INVITE is used to set up a new media session between endpoints. Think of it as a request for a new call, or IAM if you're familiar with C7 signalling.
The INVITE will contain a number of "headers" much like eMail headers or HTTP headers, these provide detail such as the calling party, and important information about call routing.
The INVITE will also typically contain session information in the form of SDP, which details how to send media to/from your endpoint
INVITE sip:email@example.com;transport=tcp SIP/2.0 Via: SIP/2.0/UDP 126.96.36.199:5060;branch=z9hG4bK6c819b34
Max-Forwards: 70 From: "441632960123" <sip:firstname.lastname@example.org>;tag=as20fb2276 To: <sip:email@example.com> Contact: <sip:firstname.lastname@example.org:5060> Call-ID: email@example.com:5060 CSeq: 102 INVITE User-Agent: Asterisk PBX 1.9 Date: Tue, 12 Dec 2017 13:27:22 GMT Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH Supported: replaces, timer Alert-Info: intercom Content-Type: application/sdp Content-Length: 239 v=0 o=root 1998461884 1998461884 IN IP4 188.8.131.52 s=Asterisk PBX 1.9 c=IN IP4 184.108.40.206 t=0 0 m=audio 33641 RTP/AVP 0 8 101 a=rtpmap:101 telephone-event/8000 a=fmtp:101 0-16 a=ptime:20 a=sendrecv
The first line after INVITE is known as the Request URI ("RURI"), this is the number you're calling so in the above the number dialled is 07700900123 shown in E.164 format (firstname.lastname@example.org;transport=tcp)
Parameters after the semi-colon are used to provide additional information, in this case this is a call that used TCP rather than the default UDP.
The Via header shows the route taken by the request and is used to route the reply. Each path generating a request appends it's own Via header.
The Via header includes the IP address responses to this request should be sent to.
The From header denotes the originating party and will be used as CLI if no P-Asserted-Identity header is provided
The To: line also shows the dialled party, although it's important to note that the RURI is what is used to route the call, not the To line.
The Call ID is unique and generated by the originating UA. Each call had a unique Call ID and this information can be useful when identifying calls.
CSeq is a Command Sequence number and is required in every request, typically this will be incremented by 1 with each new request.
This can be used to determine if a request is new or re-transmitted (i.e. a reply was never received)
A CANCEL or ACK request will always contain the same CSeq number of the INVITE message it is replying to.
The Contact header is used for sending future requests (such as ACK and BYE) relating to this call.
The body of an INVITE request is an SDP ("Session Description Protocol") message, that defines the media attribtues for the call.
This information is used to negotiate the media on the call between endpoints (e.g. what IP media should be sent to/from and also what codec(s) to offer)
This is the "version" line, and is always v=0
This is the "origin" line, and contains useful information, although is not used for call routing purposes. The first parameter ("root" in this example) is the username on the host, although often this is populated with a dummy value. The next is the session ID, whilst there's no standard for this most SIP platforms use a unix timestamp for this value. The next parameter is the session version, again it is recommended the timestamp is used here. The next two will always be "IN" (Internet) and "IP4" (IPv4) followed, finally, by the IP address of the machine which created the session.
This is the "subject" line, and is typically "SIP Call", the name of the PBX (e.g. Asterisk) or empty; it's not used by the SIP platform.
This is the "contact" or "connection" line, and contains the IP address for the RTP media.
This is the "media" line and defines the port to be used, together with the codecs supported e.g. m=audio 33641 RTP/AVP 0 8 101
Looking at this in turn; 'audio' denotes that this is a voice call, '33641' is the port that will be used for RTP media.
RTP/AVP followed by digits denote the codec offers, 0 and 8 are "reserved" and always represent PCMU (uLaw) and PCMA (aLaw) respectively, any other codes here will be defined by 'rtpmap' attributes, explained below;
These are the "attribute" lines and refer to specific codecs, for examples a=rtpmap:18 G729/8000 indicates that payload type 18 represents G.729
Another exmaple of an attribute, would be DTMF which may appears as a=rtpmap:101 telephon-event/8000 indicating that RFC2833 DTMF is being used on this call.
Packetisation time (or "ptime") is also shown in an attribute line e.g. a=ptime:20
So in our example INVITE (with SDP) we can see this is a call from 441632960123 to 447700900123 that originated from an Asterisk PBX, it's offering G711u and G711a codecs, and RFC 2833 DTMF. The PBX is at 220.127.116.11 and expects RTP media on port 33641
Almost immediately, you'll get back a 100 Trying message from us that looks like this;
SIP/2.0 100 Giving a try Via: SIP/2.0/UDP 18.104.22.168:5060;branch=z9hG4bK6c819b34 From: "441632960123" <sip:email@example.com>;tag=as20fb2276 To: <sip:firstname.lastname@example.org> Call-ID: email@example.com:5060 CSeq: 102 INVITE Content-Length: 0
This is simply an acknowledgement that the request was received, note that the CSeq number and Call ID will correspond to that in your original INVITE.
No SDP is returned at this stage, because we haven't determined the routing of the call, or if it will even complete.
180 Ringing / 183 Session Progress
Here is where the paths can diverge a bit, assuming the number was valid, all fraud checks passed, and you've got credit on your account etc the call will be passed to the PSTN and you'll get back a 180 or 183.
A 180 Ringing message indicates the call is ringing at the remote end and doesn't contain any additional information or SDP.
At this stage your PBX or phone will generate ringback tone
**** PACKET HERE ****
A 183 Session Progress is otherwise known as "Early Media", this will include RTP data, sometimes this will contain local-specific ringback tone (e.g. when calling an international destination and the remote network provides it) alternatively this is also often used for playback of a Recorded Announcement ("RCAN")
You are not charged for a call at 183 Session Progress stage so some carriers use this to play back a message indicating that a number is not in service and will subsequently follow the message with a rejection (e.g. 404)
Your call has been answered, this is the final stage of negotiating the call setup. This will look similar to the INVITE but the SDP provides information about the remote party.
**** PACKET HERE ****
The SDP lines are similar to those in the INVITE above, the c= line now contains the IP address your platform will send media to in order to be heard by the remote party, the m= line will indicate what codec to use together with any parameters in the a=rtpmap lines.
At this point the call is now established, and two way audio should take place.
Your platform should acknowledge the 200 OK. This important, if the 200 OK is not ACK'd the call will be torn down automatically after a short time.
**** PACKET HERE ****
Note that the CSeq has increased (as ACK is - somewhat counter-intuitively - considered to be a new request, not a reply) , but the Call ID remains the same.
When the call ends a BYE is sent by the party ending the call. The BYE is a simple message with the same Call ID as the original INVITE but a different CSeq.
**** PACKET HERE ****
On receipt of this BYE the call is hung up. BYE is a new request (like an INVITE) and therefore the other party will respond with a 200 OK just as they would to an INVITE.
**** PACKET HERE ****
Note that the 200 OK message contains the same CSeq as the BYE message (and indicates it's acknowledging a BYE)
When it doesn't work
The above illustrates a successful call, obviously calls occasionally fail. A failed call will never receive a 200 OK message, instead (either after the 100 Trying, or after a 183 Session Progress on occasion) you will receive a message with an error code and a human readable message.
Some common rejections are shown below, but the all have some things in common.
Usually, we will also send a Reason and/or X-Reason header in the response, these provide more detailed information on why your call failed.
Where present the Reason header will include a numeric Cause Code, this is the "ISDN Cause Code" which indicates the remote cause code received from the remote network e.g.
*** EXAMPLE HERE ***
The X-Reason header is used more for Simwood-specific messages, such as triggering a fraud prevention measure, or account balance being insufficient for the call.
** EXAMPLE FRAUD REJECTION HERE **
When a call fails you'll receive a response code in the form 4xx, 5xx or 6xx. These are similar to HTTP codes (e.g. 404 in HTTP is "Page Not Found", in SIP it's "Not Found" or "Unrecognised Number")
A typical failed call looks like this
*** EXAMPLE 404 HERE ***
In this example, the number dialled was not recognised.
As a guide, 4xx errors are specific to either the request (e.g. Bad Request) or the destination (Busy, Not Found etc) whereas 5xx errors are specific to the network (either our own, or further upstream). 6xx errors are to be considered "permanent" and shouldn't be retried.
Some of the most common (and some uncommon) codes are below
400 Bad Request
402 Payment Required
404 Not Found
406 Not Acceptable
407 Proxy Auth Required
433 Anonymity Disallowed
480 Temporarily Unavailable
481 Call/Transaction Does Not Exist
484 Address Incomplete
486 Busy Here
488 Not Acceptable Here
500 Server Internal Error
502 Bad Gateway
503 Service Unavailable
600 Busy Everywhere