2.2.1 Diagnostics Headers

This protocol supports the reporting of error and troubleshooting information from the SIP server to SIP protocol clients, for two principal purposes:

1. To convey actionable error codes, this can be used by the SIP protocol client for various error handling purposes, such as displaying an error message to the user.

2. To convey diagnostic information to help troubleshoot SIP server problems.

The primitives are defined as ms-diagnostics headers (section 2.2.1.1) and ms-diagnostics-public headers (section 2.2.1.2) that are sent by the SIP server to the SIP protocol client.

The SIP server SHOULD<1> include an ms-diagnostics header in a SIP response to indicate an error encountered while fulfilling a SIP client request or to convey additional troubleshooting information about the SIP client request. It MAY include an ms-diagnostics header in CANCEL and BYE requests to indicate an error encountered while fulfilling a SIP client request or to convey additional troubleshooting information about the SIP client request.

The ms-diagnostics header added by the SIP server can contain information that is private or of sensitive nature for the enterprise, such as information about SIP servers in the enterprise. Hence, the ms-diagnostics header SHOULD be removed from SIP responses that are sent outside the enterprise boundary. Examples of users outside the enterprise boundary are federated partners and unauthenticated users. For reporting errors and troubleshooting information to federated partners and unauthenticated users, the ms-diagnostics-public header can be used.