RFC 3326
The Reason Header Field for the Session Initiation Protocol (SIP)
RFC 3326: The Reason Header Field for SIP ✨
okay bestie, this is the RFC that gives SIP a Reason header 🎀. It's a Standards Track spec from December 2002, written by H. Schulzrinne (Columbia University), D. Oran (Cisco), and G. Camarillo (Ericsson) 🧚. The title block doesn't list any RFCs that it obsoletes or updates, so it stands on its own 💅.
Status of this Memo
Okay so this one is an Internet standards track protocol for the whole Internet community, and it's asking for discussion and suggestions for improvements 🫶. For the official standardization state and status, check the current edition of "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌸.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved. 🔒
Abstract
okay so when you're building services, it's super useful to know why a Session Initiation Protocol (SIP) request got sent in the first place 🦋. This doc defines a header field called Reason that tells you exactly that 💖. The Reason header is also meant to wrap a final status code inside a provisional response 🎀. That's needed to fix the "Heterogeneous Error Response Forking Problem", or HERFP 😭.
Table of Contents
1. Introduction ............................................... 2
1.1. Terminology ................................................ 3
2. The Reason Request Header Field ............................ 3
3. Examples ................................................... 4
3.1. Call Completed Elsewhere ................................... 4
3.2. Refusing an Offer that Comes in a Response ................. 4
3.3. Third Party Call Control ................................... 5
3.4. ISUP interworking .......................................... 5
4. IANA Considerations ........................................ 6
5. Security Considerations .................................... 6
6. Acknowledgments ............................................ 7
7. Authors' Addresses ......................................... 7
8. Normative References ....................................... 7
9. Full Copyright Statement ................................... 81. Introduction 🌷
okay so the same SIP [1] request can get sent for totally different reasons 🙈. Like, a SIP CANCEL can go out because the call already got answered on another branch, or because the caller gave up before anyone picked up 📞. The protocol behaves the same in both cases (alerting just stops) 🔔, but the user interface should totally differ. If the call was picked up elsewhere, logging it as a missed call would be so wrong 😭.
Third party call controllers sometimes make a SIP request after they get a SIP response from some other dialog 🧚. Gateways make SIP requests after they get messages from a protocol that isn't SIP 🌉. In both cases, the client might really want to know what set off that request 👀.
SIP responses already tell the user why a request failed 💅. The mechanism in this doc does something kinda similar, but for requests 💖.
An INVITE can get rejected for a reason that has nothing to do with the session being declined 🙃. Instead, some part of the request just wasn't acceptable 😤. If the INVITE forked and got rejected, the error response might never reach the client, unless every other branch also rejects the request 💀. That's the "Heterogeneous Error Response Forking Problem", or HERFP 😭. One possible fix is to wrap the final error response inside a provisional response, and the Reason header is a good candidate for that wrapping 🎀.
At first, the Reason header defined here seems most useful for BYE and CANCEL requests 📞. But it can show up in any request within a dialog, in any CANCEL request, and in any response whose status code explicitly allows this header field 🦋.
Heads up: the Reason header usually isn't needed in responses, because the status code and the reason phrase already give enough info 🌸.
Clients and servers are free to ignore this header field 🫶. It has no impact on protocol processing ✨.
1.1 Terminology 📚
In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 [2]. They indicate requirement levels for compliant SIP implementations 💜.
2. The Reason Header Field 🎀
The Reason header field MAY appear in any request within a dialog 🦋. It can also show up in any CANCEL request, and in any response whose status code explicitly allows this header field 🌈. Its syntax follows the standard SIP parameter syntax 💅.
Reason = "Reason" HCOLON reason-value *(COMMA reason-value)
reason-value = protocol *(SEMI reason-params)
protocol = "SIP" / "Q.850" / token
reason-params = protocol-cause / reason-text
/ reason-extension
protocol-cause = "cause" EQUAL cause
cause = 1*DIGIT
reason-text = "text" EQUAL quoted-string
reason-extension = generic-paramThese are the protocol values that have been defined 📝:
SIP: the cause parameter holds a SIP status code 💖.Q.850: the cause parameter holds an ITU-T Q.850 cause value, written in decimal 🔢.
Here are some examples 👀:
Reason: SIP ;cause=200 ;text="Call completed elsewhere"
Reason: Q.850 ;cause=16 ;text="Terminated"
Reason: SIP ;cause=600 ;text="Busy Everywhere"
Reason: SIP ;cause=580 ;text="Precondition Failure"okay so when a proxy gets a CANCEL from the previous hop that has a Reason header, and it generates a new CANCEL, it SHOULD copy that Reason header into the new CANCEL 🫶.
In normal SIP operation, a status code in a response tells the client about the request that set it off, the session parameters, or the user 🧠. For example, a 405 (Method not allowed) means the request had a method that isn't supported 🙅. A 488 (Not Acceptable Here) means the session parameters aren't acceptable 🙅♀️. A 486 (Busy Here) tells you about the user's status 📞.
Any SIP status code MAY appear in the Reason header field of a request 🌸. Still, codes about the user and session parameters are usually the useful ones for building services 💅. Codes that report errors about a request are usually more useful for debugging 🐛.
A SIP message MAY contain more than one Reason value, meaning multiple Reason lines 🦋. But all of them MUST have different protocol values, like one SIP and another Q.850 ⚠️. An implementation is free to ignore any Reason values it doesn't understand 💖.
3. Examples 🧚
This section has a bunch of examples showing how to use the Reason header field 📖.
3.1 Call Completed Elsewhere 📞
A proxy forks an INVITE request, and one of the branches comes back with a 200 (OK) 🎉. The forking proxy puts that status code into a Reason header field inside the CANCEL it sends to the other branches 💅.
3.2 Refusing an Offer that Comes in a Response 🙅♀️
A client sends an empty INVITE and gets an unacceptable offer in a 200 (OK) response 😤. It sends an ACK with a properly formatted answer, then immediately sends a BYE to end the session 💀. The client puts a 488 (Not Acceptable Here) status code in a Reason header field 🎀.
3.3 Third Party Call Control 🧚
The third party call controller in figure 1 tries to set up a session between A and B 📞. But user B is busy 📵. The controller sends a BYE with status code 486 (Busy Here) in a Reason header field 🫶.
A Controller B
| INV no SDP | |
|<------------------| |
| | |
| 200 SDP A1 | |
|-----------------> | |
| | |
| ACK SDP held | |
|<------------------| |
| | |
| | INV no SDP |
| |----------------->|
| | |
| | 486 Busy Here |
| |<-----------------|
| | |
| | ACK |
| |----------------->|
| BYE (486) | |
|<------------------| |
| | |
| 200 OK | |
|-----------------> | |
| | |
Figure 1: Third Party Call Control3.4 ISUP interworking 🌉
The PSTN gateway in figure 2 generates an INVITE, and that INVITE has to be CANCELed when a REL (release) message comes in from the ISUP side 📡. The CANCEL request carries the Q.850 cause value (16 Normal Call Clearing) from the REL message 🔢.
A Gateway B
| IAM | |
|-----------------> | |
| | INVITE |
| |----------------->|
| | |
| | 100 Trying |
| |<-----------------|
| REL (16) | |
|-----------------> | |
| | CANCEL (Q.850 16)|
| |----------------->|
| | 200 OK |
| |<-----------------|
Figure 2: ISUP Interworking4. IANA Considerations 🗂️
This document defines a new SIP header field called "Reason", as described in Section 27 of RFC 3261 🎀.
The protocol values, and their matching protocol causes, that go with this header field get registered by IANA into a new sub-registry under http://www.iana.org/assignments/sip-parameters, called "Reason Protocols" 📋. Reason protocols MUST refer to one of these: an ITU-T Recommendation number, an IETF protocol name, or the recognized protocol identifier from another standardization organization 💜. The protocol cause describes where the 'cause' field in the Reason header field comes from 🧠.
For now, the only entries in the registry are these 👇:
Protocol Value Protocol Cause Reference
-------------- --------------- -----------
SIP Status code RFC 3261
Q.850 Cause value in decimal ITU-T Q.850
representation5. Security Considerations 🔐
okay bestie, this part is serious, so no cap, pay attention 👀 spoofing or removing the Reason header field from a response in a HERFP scenario can make it impossible for a client to properly update its previous request, which means session establishment just... doesn't happen 😭 so it is RECOMMENDED that this header field is protected by a suitable integrity mechanism 🛡️✨
properly its previous request, making therefore session establishment impossible. Thus, it is RECOMMENDED that this header field is protected by a suitable integrity mechanism. 💅
6. Acknowledgments 🫶
Jonathan Rosenberg, Rohan Mahy and Vijay K. Gurbani provided helpful comments and suggestions. Thank you, queens 👑💖
8. Normative References 📚
[1] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[2] Bradner, S., "Key words for use in RFCs to indicate requirement
levels," BCP 14, RFC 2119, March 1997.7. Authors' Addresses 🎀
Henning Schulzrinne
Dept. of Computer Science
Columbia University
1214 Amsterdam Avenue
New York, NY 10027
USA
EMail: schulzrinne@cs.columbia.edu
David R. Oran
Cisco Systems, Inc.
Acton, MA
USA
EMail: oran@cisco.com
Gonzalo Camarillo
Ericsson
Advanced Signalling Research Lab.
FIN-02420 Jorvas
Finland
EMail: Gonzalo.Camarillo@ericsson.com9. Full Copyright Statement 🌈
Copyright (C) The Internet Society (2002). All Rights Reserved. 🦋
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. ♾️
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 💀
Acknowledgement 🍓
Funding for the RFC Editor function is currently provided by the Internet Society. 💜
📦 where this page comes from
- ietf: rfc3326 2002-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms