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.

After you have 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, for example, 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 the reasonCode value as empty.

The SBC behaves differently when there is a single or multiple reason values presented.

Single Reason Values in Responses

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 is one of the following:
    • For all responses: reasonCode, if it is included in JSON body
    • If reasonCode is not included in the JSON body:
      • For 4xx/5xx responses: HTTP response code
      • For 200 OK responses with ATIS: 403
      • For 200 OK responses with 3GPP: No reason header is sent.
  • text is one of the following:
    • For all responses: reasonText, if it is included in JSON body
    • If reasonText is not included in the JSON body:
      • For 4xx/5xx responses: error, if it is included in JSON body, or HTTP reason phrase, if neither reasonText nor error is included in JSON body
      • For 200 OK responses with ATIS: Forbidden
      • For 200 OK responses with 3GPP: No reason header is sent.

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"
      ]
    }
  }
}

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 no 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" 
 } 
}

For 3GPP and ATIS, no reason header is sent.

Multiple Reason Values in Response

In the case of 3GPP, for 4xx/5xx responses, 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 verifications.

For 200 OK responses, the SBC includes only the cause and text specific to the shaken PASSporT verification, ignoring the div reason values.

Multiple Reason Values - Example 1

For example, when the JSON body includes multiple reasonCode and reasonText objects, 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"

Multiple Reason Values - Example 2

When the JSON body for a 200 OK response includes multiple reasonCode and reasonText objects, the HTTP Response may appear as follows:

{
  "verificationResponse": {
    "verifyResults": [
      {
        "verifyResult": {
          "ppt": "shaken",
          "status": "fail",
          "reasonCode": 437,
          "reasonText": "Stale Date"
        }
      },
      {
        "verifyResult": {
          "ppt": "div",
          "status": "fail",
          "reasonCode": 438,
          "reasonText": "divreasontext1"
        }
      }
    ],
    "divResult": [
      {
        "div": {
          "tn": "16035550100"
        },
        "verstatValue": "TN-Validation-Failed"
      }
    ],
    "verstatValue": "TN-Validation-Failed"
  }
}

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

Reason: SIP;cause=437;text="Stale Date"