Including STI-VS Failure Reasons in INVITEs

When you enable the man-compliance option in the sti-config, the SBC adds STI-VS failure reasons information to SIP reason headers for applicable egress INVITE messages. This improves your ability to identify failure scenarios.

Having enabled man-compliance, the SBC populates SIP Reason headers in egress INVITEs with STI-VS failure information after receiving a 4xx/5xx answer from an STI-VS request, including:

  • HTTP response code
  • JSON reason phrase/text as described in ATIS 1000082 (8.2.4.6 HTTP Response Codes) and in 3GPP TS 124 229 (V.2.4.3.2 Service errors)

Additional behaviors include:

  • If the reason code is empty, eg, reasonCode: "", the system uses the HTTP response code.
  • If the reason code is a string within the double quotes, for example reasonCode: "438", then the system treats reasoncode value as empty.

The SBC behaves differently when there is a single or multiple reason values presented. This section proceeds with descriptions of behaviors following single reason values first, and then multiple values. Examples of each are included.

When there is a single reason value in the HTTP response in either ATIS or 3GPP mode, the SBC populates the SIP Reason Header as follows:

  • cause:
    • reasonCode (included in JSON body)
    • OR HTTP response code if reasonCode is not available in JSON body
  • text:
    • reasonText (included in JSON body)
    • OR error (included in JSON body) if reasonText is not available in JSON body
    • OR HTTP reason phrase if reasonText or error is available in JSON body

Single Reason Value - Example 1

In this case, the reasonCode and reasonText are included in the JSON Body. The HTTP response may appear as follows.

HTTP/1.1 430 Bad Request
X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836 
Content-Type: application/json 
Content-Length: …
{
"verificationResponse": {
"verifyResults": [
 {
"verifyResult": {
"status": "fail",
"ppt": "shaken",
"reasonCode": 438,
"reasonText": "Bad Identity Info",
 "passport": "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsIn....."
 }
 }
 ],
 "verstatValue": "TN-Validation-Failed"
 }
}

In this case, the Expected Reason header is as follows.

Reason: SIP ; cause=438 ;text="Bad Identity Info"

Single Reason Value - Example 2

In this case, the reasonCode and error are not included in the JSON Body, but error text is included in the JSON Body. The HTTP response may appear as follows.

HTTP/1.1 400 Bad Request 
X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836
Content-Type: application/json
Content-Length: …
{
 “requestError”:
      {“serviceException”: {“messageId”: “SVC4001”
 “text”:
      “Error: Missing mandatory parameter ‘%1’”,“variables”:
      [“iat”]}         }}
Expected Reason header:
Reason: SIP ; cause=400 ;text=" Error: Missing mandatory parameter ‘%1’"

In this case, the Expected Reason header is as follows.

Reason: SIP ; cause=400 ;text=" Error: Missing mandatory parameter iat

Single Reason Value - Example 3

In this case, the reasonCode is included in the JSON Body, but no reasonText or error text is included. The HTTP response may appear as follows.

HTTP/1.1 430 Bad Request
X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836 
Content-Type: application/json
Content-Length: …
{
 "verificationResponse": {
 "verifyResults": [
 {
 "verifyResult": {
"status": "fail",
 "ppt": "shaken",
"reasonCode": 438,
 "passport": "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsIn....."
 }
 }
 ],
 "verstatValue": "TN-Validation-Failed"
 }
 }
 }

In this case, the Expected Reason header is as follows.

Reason: SIP;cause=438;text="Bad Request"

Single Reason Value - Example 4

In this case, the Response is a 200OK, and neither the reasonCode, reasonText or error text is included in the JSON Body. The HTTP response may appear as follows.

HTTP/1.1 200 OK 
X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836
Content-Type: application/json
Content-Length: … 
{ 
 "verificationResponse": { 
 “verstat”: “TN-Validation-Passed” 
 } 
}

In this case, the Expected Reason header is None. The Reason header is not populated in this scenario.

Multiple Reason Values in Response

In the case of 3GPP, if the response from STI server includes multiple reason values, the SBC includes two reason values in the SIP Reason header:

  • cause and text specific to shaken PASSporT verification
  • cause and text specific to first div PASSporT verification

It is assumed that the STI-VS always returns a SHAKEN PASSporT verification on top of the JSON body, followed by any DIV PASSporT verification(s). For example, consider the scenario wherein there are multiple reasonCode and reasonText objects included in the JSON Body. In this case, the HTTP Response may appear as follows.

{"verificationResponse":
{"verifyResults": [
 {"verifyResult": {"status": "fail", "ppt": "shaken", "reasonCode": 438, "reasonText": "Identity signature payload does not match the re-constructed one", "passport": "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsIn....."}},
{"verifyResult": {"status": "fail", "ppt": "div", "reasonCode": 438, "reasonText": "Identity signature payload does not match the re-constructed one", "passport": "eyJhbGciOiJFUzI1NiIsInBwdCI6uPuDqJ8ua..........."}}
 ],
"verstatValue": "TN-Validation-Failed"
 }
 }

In this case, the Expected Reason header is as follows.

Reason: SIP ; cause=438 ;text="Identity signature payload does not match the re-constructed one"; cause=438 ;text=" Identity signature payload does not match the re-constructed one"