Error Handling

When handling PI Web API responses in your client application, it is recommended to apply error handling logic in order to verify the integrity of your data. This topic will highlight the different types of errors PI Web API may return, and how a client should interpret them.

Status Code

The best indicator for determining the integrity of the response is the response HTTP Status Code. Any HTTP Status Code in the 200-300 range can be considered a successful PI Web API response. Any status code in the 400-500 range indicates a user or server error occurred. These are generally accompanied by a response body providing a friendly error message to assist with debugging. For more information on interpreting the Status Code returned by PI Web API, see the 'Status Code' section of our 'Getting Started' guide.

Example Response Body:

{
    "Errors": [
        "The version of the AF Server does not support the feature SecurityIdentity."
    ]
}

Web Exception

Introduced in PI Web API 2017 R2, PI Web API now exposes a 'WebException' property on all controller responses.

Any PI Web API response containing a 'WebException' property which is non-null indicates that PI Web API encountered an unhandled error during the transfer of the response stream. These errors can occur despite PI Web API responding with a successful HTTP status code. Responses will not contain a 'WebException' if no error occurred. When present, the 'WebException' property will be present at the top level of all response objects. A 'WebException' contains a 'StatusCode' field, which indicates the correct error HTTP Status Code the client should interpret the response as returning with.

Example Response Body:

{
    "WebException": {
        "Errors": [
            "Error occurred during writing of the output stream."
        ],
        "StatusCode": 500
    }
}

Stream and Stream Set Controller Responses: Errors

The Stream and Stream Set controller responses may contain an additional field called 'Errors' in the response. The purpose of the 'Errors' field is to indicate that an error occurred for a particular value while streaming the response. For example, if there are 100 values returned and one of them has an associated error, the remaining 99 values do not need to be discarded. Values will not contain an 'Errors' property if no error occurred. Each object in the list of 'Errors' contains which field name caused an error, as well as the exception message.

Unlike 'WebException', which is a single property found at the top level of the response object, an 'Errors' property may be present on any stream value. If a stream value contains an 'Errors' property then its value will be 'null'. If any stream values in the response contain an 'Errors' field, that does not mean the entire value collection returned is invalid.

Example Response Body:

{
    "Timestamp": "2014-07-22T14:00:00Z",
    "UnitsAbbreviation": null,
    "Good": true,
    "Questionable": false,
    "Substituted": false,
    "Value": null,
    "Errors": [
        {
            "FieldName": "UnitsAbbreviation",
            "Message": [
                "PI Point not found."
            ]
        },
        {
            "FieldName": "Value",
            "Message": [
                "PI Point not found."
            ]
        }
    ]
}

Notes: There are a couple of things that the user must be aware of when using the Stream or Stream Set controllers.

Enabling Operational Intelligence