SIF Error Handling

1 Overview
2 Error Message Payload - Core
- 2.1 XML
- 2.2 JSON (PESC)
- 2.3 JSON (Goessner)
3 Enriched Error Message (since SIF 3.6 Infrastructure)
4 Assumptions & Constraints

Overview

Since SIF APIs are REST APIs the overall error handling is no different as intended by the HTTP standard. Basically errors are first and foremost based around HTTP error status codes. As per HTTP standard status codes of 2XX and 3XX indicate that the action requested by the issuing Service Consumer was received, understood, accepted and processed successfully. HTTP status codes of 4XX and 5XX indicate some sort of an error.

SIF has defined an Error Message structure that can be returned as a payload by a service endpoint in case of an error. It is intended that SIF endpoint providers use the SIF error message to further indicate the nature, cause and potential solution for a particular error.

Please refer to the Open API documentation for applicable error codes for each locale’s data model and the infrastructure APIs.

Error Message Payload - Core

The general error message structure is outlined below. The exact definition (XSD or Open API documentation) for the error message structure can be found as part of the Open API documentation or the SIF Infrastructure Data Model documentation.

XML

<error id="5b72f2d4-7a83-4297-a71f-8b5fb26cbf14">
  <code>401</code>
  <scope>Provider</scope>
  <message>Authorisation failed.</message>
  <description>Invalid or missing 'Authorization' HTTP Header.</description>
</error>

JSON (PESC)

{
  "error": {
    "id": "5b72f2d4-7a83-4297-a71f-8b5fb26cbf14",
    "code": 401,
    "scope": "Provider",
    "message": "Authorisation failed.",
    "description": "Invalid or missing 'Authorization' HTTP Header."
  }
}

JSON (Goessner)

{
  "error": {
    "@id": "5b72f2d4-7a83-4297-a71f-8b5fb26cbf14",
    "code": "401",
    "scope": "Provider",
    "message": "Authorisation failed.",
    "description": "Invalid or missing 'Authorization' HTTP Header."
  }
}

Enriched Error Message (since SIF 3.6 Infrastructure)

SIF 3.6 extended the Core Error Message structure to enable more flexibility to enrich error messages. The Core Error Message structure is still valid and supported, to ensure backward compatibility, and is intended to provide an overall error message. However, the error message structure has been extended allowing a list of more detailed error messages. This can be particularly useful in cases where the Core Error Message might be ambiguous or where a provider detects several different errors. The extended Error Message allows a sub-list of error details to be returned to the service consumer and each error can be further qualified with a sub-error code and a type. An example (XML) is provide below to highlight the extensions.

The optional errorDetails node is new and allows a list of errors to be returned to the service consumer. It is intended to be used to further quantify an error. There are several reasons why such a quantification might be useful. These are:

Resolve ambiguity: There are situations where a specific error code such a 410 (Gone) could relate to more than one error. For example the SIF infrastructure uses this error code for expired “changes since markers” and “privacy marker”. One or both could be expired.
Provide multiple errors in one message: Especially for locale data models it is entirely possible that there are several issues with the provided data. Data can fail basic validation (e.g. invalid date) as well as conceptual validation (e.g. student already enrolled in a school).
Combination of the above!

To indicate if an error relates to infrastructure or data related to the locale data model an optional type node has been introduced. It indicates what the specific error relate to and it can have a value of INFRASTRUCTURE or DATA.

A additional and optional node called subCode can be used to further quantify the error where there might be ambiguity. This sub-code is of a type string. If the error is of type INFRASTRUCTURE then these sub-codes are defined as part of the SIF Infrastructure. However, if the error type is DATA then it is up to the locale to define what valid sub-codes are and how they are intended to be used in either use-cases or data validations.

Assumptions & Constraints

Please note that a service consumer should not assume that an error message payload is always returned by the endpoint provider. Some implementations are more vigilant than others and may consistently provide an error message payload while other implementations may not. There is a potential that some proxies or other network filters may remove payloads from a HTTP response for certain HTTP error status codes. A typical case where it is unlikely that a SIF structured error payload is returned in a response is the HTTP 404 (Not Found). This error code is typically returned if an incorrect URL is used. In such a case the actual endpoint provider is not reached and hence a SIF error message payload is not produced.

Software providing error payloads shall not include actual data within the message. It may be specific as to what field has an issue, but not what was supplied. This will help prevent both fragile workflows and privacy violations as none of the usual validity or privacy checks can be applied to data included in the structure defined here.