_To be released with version 3.1. _

TODO: add a list of standardized warnings and needs attributes Warning.code and Warning.details added

Open Question: Do we need a namespace for the errors and warnings?

Errors and Warnings

General HTTP error codes and generic situations

The following standard HTTP error codes are used in the specification:

Functional Errors

The OSDM API makes use of the JSON Problem structure to return information about functional errors in the handling of a request. The problem structure is defined in RfC-7807 which defines a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

For OSDM, the code property should begin with the code of the error type. This code should be the unique identifier for the functional situation in the absolute URI in the type property as well.

The title is a short, human-readable summary of the problem type which should not change from occurrence to occurrence of the problem. The detail is a human-readable explanation specific to this occurrence of the problem. The status is the HTTP status code generated by the origin server for this occurrence of the problem.

"problem": {
  "code": "PLACE_NO_RESULTS",
  "type": "https://osdm.io/errors/place-no-results",
  "title": "The search did not return any result",
  "detail": "The place `Duckburg` could not be found",
  "status": 404,
}

The list of all error codes that can be returned by the API, needs to exposed on an URI:

https://<host>/errors/<error-code>

where host denotes the host of the API.

Standardized Functional Errors

In order that OSDM implementations behave consistently in error situations, the following error codes must be supported in case of functional errors by all implementations:

The list can be extended by an implementor but at least these errors must be captured and they must be presented with the codes listed here above.

In case they wish to pass additional warnings specific to their situation and not covered by any of the case below, they can do so by replacing the OSDM prefix with an X_ followed by an unique identifier for the provider (ex: X_NVS_NOMEAL).

Functional Warnings

In addition to errors, a generic warnings mechanism is used to pass non-blocking information or events, such as a price difference with the initially offered price at booking time to the caller.

A warning message is typically made of a code and a detail. The details are not translated and the expected language there should be in English. It is up to the implementers to foresee a translation based on the code if relevant. Optionally, a warning message can contain reference to resources in the model.

"warning": {
  "code": "PLACE_PROPERTY_NOT_RESPECTED",
  "type": "https://osdm.io/warnings/place-property-not-respected",
  "title": "Place property not respected",
  "detail": "Place property `WINDOW` is not respected in offer with id `123456`",
}

Standardized Functional Warnings

In order that OSDM implementations behave consistently in warning situations, the following warning codes must be supported in case of functional warnings by all implementations:

As for the warnings, an implementor is required to use these warning codes and descriptions for the situations identified in order to be compliant.

In case they wish to pass additional warnings specific to their situation and not covered by any of the case below, they can do so by replacing the OSDM prefix with an X_ followed by an unique identifier for the provider (ex: X_NVS_NOMEAL).

Dealing with Unsupported Parameters in Requests

Some OSDM requests potentially support a large number of parameters (e.g. filters). Supporting all of them is not always possible, e.g. due restrictions of the underlying systems. Thus the following rule applies:

• If the parameter is required, return an error “NOT SUPPORTED”.
• If the parameter is optional, return a response including a warning indicating that the optional request parameter was ignored.