Decoding the SIP Reason Header (RFC 3326): Mapping ISUP Cause Codes to SIP Disconnect Reasons

Overview

Key takeaways

• RFC 3326 defines the Reason header field to convey why a SIP request was issued or why a call was terminated.
• The Reason header bridges the gap between PSTN ISUP cause codes (ITU-T Q.850) and native SIP status codes.
• Common ISUP cause codes such as Cause 16 (Normal Clearing), Cause 17 (User Busy), and Cause 31 (Normal Unspecified) map directly to standardized SIP equivalents under RFC 3398.
• Session Border Controllers rely on the Reason header to pass precise release semantics across multi-hop SIP networks without losing legacy ISUP diagnostic context.

Prerequisites

• Understanding of fundamental SIP architecture, dialogs, and transactions (INVITE, BYE, CANCEL).
• Familiarity with PSTN signaling concepts, SS7, ISUP, and ITU-T Q.850 cause codes.
• Basic knowledge of SBC routing rules and SIP protocol analysis tools like Wireshark.

Guide

1. section #1

   The Purpose of RFC 3326 in Hybrid VoIP/PSTN Networks When a SIP request such as BYE or CANCEL is issued, or when a final response is returned, the base SIP protocol (RFC 3261) provides limited diagnostic context regarding why the transaction occurred. In legacy PSTN environments, ISUP (ISDN User Part) signaling utilizes explicit ITU-T Q.850 cause codes to communicate precise disconnection semantics. RFC 3326 addresses this gap by defining the 'Reason' header field. This header carries detailed cause codes and protocol references—most commonly ISUP Q.850—allowing SIP entities to preserve full diagnostic telemetry when translating between PSTN and IP domains.

2. section #2

   SIP Reason Header Syntax and Parameters The Reason header grammar supports multiple protocol domains, though 'Q.850' and 'SIP' are the primary values encountered in production networks. The header consists of a protocol identifier, a mandatory cause parameter, and optional text or extension parameters. Multiple Reason headers can also be stacked within a single SIP message if a call termination was triggered by several cascading protocol layers.

   httpcopy

   Reason: Q.850 ;cause=16 ;text="Normal Clearing"
   Reason: SIP ;cause=200 ;text="Call completed elsewhere"
   Reason: Q.850 ;cause=31 ;text="Normal, unspecified"

3. section #3

   Standard ISUP Q.850 to SIP Response Code Mappings (RFC 3398) RFC 3398 establishes the official interworking specifications between ISUP and SIP status codes. When an MGCF or SBC receives an ISUP Release (REL) message with a Q.850 cause code, it translates that value into a corresponding SIP response code while embedding the exact original Q.850 code inside the Reason header. Key mappings include: Cause 1 (Unallocated number) to 404 Not Found, Cause 17 (User busy) to 486 Busy Here, Cause 18 (No user responding) to 408 Request Timeout, Cause 21 (Call rejected) to 603 Decline, Cause 34 (Circuit unavailable) to 503 Service Unavailable, and Cause 41 (Temporary failure) to 503 Service Unavailable.

   textcopy

   +-------------------+-----------------------+-----------------------+
   | Q.850 Cause Code  | Description           | SIP Equivalent Code   |
   +-------------------+-----------------------+-----------------------+
   | 1                 | Unallocated Number    | 404 Not Found         |
   | 16                | Normal Clearing       | 200 OK / BYE          |
   | 17                | User Busy             | 486 Busy Here         |
   | 18                | No User Responding    | 408 Request Timeout   |
   | 19                | No Answer (Alerted)   | 480 Temporarily Unavail|
   | 21                | Call Rejected         | 603 Decline           |
   | 34                | Circuit Unavailable   | 503 Service Unavail   |
   | 41                | Temporary Failure     | 503 Service Unavail   |
   +-------------------+-----------------------+-----------------------+

4. section #4

   Handling BYE and CANCEL Requests with Reason Headers Reason headers are vital during CANCEL and BYE operations. For instance, in parallel or serial call-forking scenarios, when an endpoint answers a call, the PBX sends a CANCEL to all remaining ringing endpoints. Including 'Reason: SIP ;cause=200 ;text="Call completed elsewhere"' prevents those endpoints from registering a missed call in their local logs. Similarly, when a carrier initiates a BYE due to media timeout or prepaid balance exhaustion, the BYE request includes a Q.850 Reason header (e.g., cause=31 or cause=102) to notify the billing system and endpoint of the underlying driver.

   httpcopy

   CANCEL sip:user@10.0.0.50:5060 SIP/2.0
   Via: SIP/2.0/UDP 10.0.0.1:5060;branch=z9hG4bK-1234
   From: <sip:caller@example.com>;tag=src1
   To: <sip:user@example.com>
   Call-ID: c3a411a0-892b@10.0.0.1
   CSeq: 1 CANCEL
   Reason: SIP ;cause=200 ;text="Call completed elsewhere"
   Content-Length: 0

5. section #5

   Configuring SBCs to Preserve and Manipulate Reason Headers Modern Session Border Controllers (such as Ribbon, AudioCodes, or Oracle Enterprise SBCs) offer explicit controls to manipulate, pass-through, or strip Reason headers based on peer trust boundaries. While internal core networks rely on Q.850 headers for accurate billing, detailed CDR generation, and routing optimization, security policies might require masking internal failure causes when sending messages to untrusted public carriers. SBC profile settings allow engineers to enforce RFC 3326 transparency on trusted interconnects while sanitizing or re-mapping causes on external legs.

   textcopy

   # Example conceptual SBC Header Manipulation Rule (HMR)
   header-rule
       name: PreserveQ850Reason
       header-name: Reason
       action: passthrough
       match-value: "Q.850*"
       msg-type: ANY

6. section #6

   Troubleshooting Call Failures using Wireshark and Reason Headers When analyzing PCAP captures of failed call attempts, the outer SIP status code (such as 503 Service Unavailable) may be too generic to identify root causes. By inspecting the embedded Reason header in Wireshark (filter: sip.Reason), engineers can isolate whether a failure originated from upstream PSTN congestion (Q.850 cause 34/41), ISUP routing failure (cause 27), or local resource exhaustion. Combining the SIP status code with the raw Q.850 cause enables fast pinpointing of carrier interop issues.

   httpcopy

   SIP/2.0 503 Service Unavailable
   Via: SIP/2.0/UDP 192.168.1.10:5060;branch=z9hG4bK99a87
   From: <sip:5551234@carrier.com>;tag=a1b2c3
   To: <sip:5555678@customer.com>;tag=x7y8z9
   Call-ID: 887123910@192.168.1.10
   CSeq: 101 INVITE
   Reason: Q.850 ;cause=34 ;text="No circuit/channel available"
   Server: Carrier-MGCF-Gateway
   Content-Length: 0

Further reading

• RFC 3326 - The Reason Header Field for the Session Initiation Protocol (SIP)
• RFC 3398 - Integrated Services Digital Network (ISDN) User Part (ISUP) to Session Initiation Protocol (SIP) Mapping
• ITU-T Recommendation Q.850 - Usage of Cause and Location in the Digital Subscriber Signalling System No. 1 and the Signalling System No. 7 ISDN User Part