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)
- 3.1 Sub-Error Codes
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.

When sending error information you must be as specific as possible. Specific codes are specified in various sections of this documentation. The following table is maintained as a quick reference to aid in clarity.

Error Code	Meaning	Example of Use	Example Service
400	Bad Request	XML error, version problems or error specific to a particular object type such as the omission of a mandatory element or an unsupported query or an unsupported order clause	Object
401	Unauthorized	Illegal Consumer Authorization token accompanying the request	Environment
403	Forbidden	Consumer Authorization token is legal, but Consumer is not authorized to issue the requested operation	Utility
404	Not Found	Object ID does not correspond to an existing object. This can occur for Query as well as Update or Delete operations No Service Provider has been found to match the parameters (Zone, Context, Service name) in the Request.	Object
405	Method not Allowed	Paged Query Request issued to Object URL rather than Object List URL. Create Request issued to Provider Registry Service in a Direct Zone.	Object
409	State Conflict	An attempt has been made to create an existing object. Attempt to create an Environment with an applicationKey for which an environment does already exist (and multiple instances are not configured).	Environment
410	Gone	“ChangesSinceMarker” and/or “DataPrivacyMarker” expired	Object
412	Precondition Failed	An attempt has been made to modify an object when the Requester was not basing the modification on the latest version.	Object
413	Response too large	A non-paged Query returning all objects was too large for the Service Provider (or Broker) to include in a single Response message.	Object
415	Unsupported Media Type	Un unsupported data format was detected.	Environment
500	Internal Service Error	An unexpected error occurred in servicing the Request.	Object
501	Not Implemented	The server does not support the functionality required to fulfill the request.	ServicePath
503	Service Unavailable	Returned only for Consumer Requests requiring an immediate Response. This error indicates that the expected Service processing time for the Request is great enough that the Consumer must reissue it as a Request requiring a delayed Response.	Object

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.

<error id="5b72f2d4-7a83-4297-a71f-8b5fb26cbf14">
  <code>410</code>
  <scope>Provider</scope>
  <type>INFRASTRUCTURE</type> <!-- NEW -->
  <subCode>001</subCode> <!-- NEW -->
  <message>Gone</message>
  <description>The provided HTTP header dataPrivacyMarker is no longer valid.</description>

  <errorDetails> <!-- EXTENSION: NEW and optional -->
    <errorDetail id="89209C52-E5C4-416F-BBAF-974D09AA79F4">
      <type>INFRASTRUCTURE</type> <!-- NEW -->
      <subCode>001</subCode> <!-- NEW -->
      <message>Invalid dataPrivacyMarker</message>
      <description>The provided HTTP header dataPrivacyMarker is no longer valid.</description> 
    </errorDetail>
    <errorDetail id="0394E69C-4A73-4755-9C92-A64FA7F16AB8">
      <type>INFRASTRUCTURE</type> <!-- NEW -->
      <subCode>002</subCode> <!-- NEW -->
      <message>Invalid changesSinceMarker</message>
      <description>The provided URL Query parameter changesSinceMarker is no longer valid.</description> 
    </errorDetail>
    <errorDetail id="E60BCFE3-7ACC-4A69-9634-32FB99377F80">
      <type>DATA</type> <!-- NEW -->
      <subCode>2001</subCode> <!-- NEW -->
      <message>Invalid birthdate</message>
      <description>The student’s birthdate is a future date.</description> 
    </errorDetail>
    <errorDetail id="39B434FB-42F3-4FAA-9163-ED25801C7F9A">
      <type>DATA</type> <!-- NEW -->
      <subCode>2017</subCode> <!-- NEW -->
      <message>Already Enrolled</message>
      <description>The student is already enrolled at another school</description> 
    </errorDetail>
  </errorDetails>
</error>

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.

Sub-Error Codes

The list below defines some sub-error codes that should be used when further error details are provided in context of infrastructure issues. This list is not definite and will grow over time as functionality and or clarity is added to various areas of the SIF Infrastructure specification. It is important to note that the list below mostly applies for errors in context of concepts or functionality specified by the SIF infrastructure. They may apply to infrastructure and data model services in more general terms. Locale’s Data model use-cases may have their own sub-error code lists specifically related to the use-case and its usage. These sub-codes will be specified in each locale’s Data Model specification rather than in the infrastructure specification.

Sub-Code	Type	Meaning	Potential usage

Sub-Code	Type	Meaning	Potential usage
400-01	INFRASTRUCTURE & DATA	Schema validation error.
400-02	DATA	Unsupported query.
400-03	DATA	Unsupported order clause.
400-04	INFRASTRUCTURE	Request must be made asynchronously.
400-05	INFRASTRUCTURE	Request must be made synchronously.
404-01	INFRASTRUCTURE	Invalid or non-existent path-based resource reference.	The requested resource, as indicated by the URL path, does not exist or the provided path value is invalid.
404-02	INFRASTRUCTURE	Invalid or non-existent scoping parameter.	The provided scoping parameter does not refer to any known resource or is invalid. This applies whether the parameter is conveyed via matrix parameters or headers (e.g., zoneId, contextId).
404-03	INFRASTRUCTURE	Invalid or non-existent queue management parameter.	The provided deleteMessageId does not reference any known message in the queue, indicating the parameter is invalid or the resource does not exist. For more details refer to Queue & Message Service & API \| Get Next Message
409-01	INFRASTRUCTURE & DATA	Request to create an object that already exists.	An attempt was made by a consumer to create an environment but it already exist.
409-02	INFRASTRUCTURE & DATA	The ‘zoneId’ has been provided as a matrix parameter and HTTP header.	For more details refer to SIF Zone \| Conveying Zone
409-03	INFRASTRUCTURE & DATA	The ‘contextId’ has been provided as a matrix parameter and HTTP header.	For more details refer to SIF Context \| Conveying Context
410-01	INFRASTRUCTURE & DATA	The ‘changesSinceMarker’ has expired.	For details refer to "Changes Since" Functionality \| Expired “Changes Since” marker
410-02	DATA	The ‘dataPrivacyMarker’ has expired.

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.