Errors and Problems

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-9457 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 following properties are supported:

A problem message is typically made of a code, title and a detail. The title and detail 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 problem message can contain reference to resources in the model.

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.

Examples

No result found for given request

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

Request not conform OpenAPI schema

"problem": {
  "code": "urn:uic:problem:MALFORMED_REQUEST",
  "type": "https://osdm.io/errors/malformed_request",
  "title": "Request failed schema validation",
  "detail": "The request does not validate the OSDM OpenAPI schema specification",
  "status": 400,
}

Request with invalid input

"problem": {
  "code": "urn:uic:problem:VALIDATION_ERROR",
  "type": "https://provider.domain/osdm/documentation/errors/validation_error",
  "title": "Passenger details missing",
  "detail": "The passenger does not contain all mandatory information to confirm the booking",
  "status": 400,
}

Standardized Technical Errors

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

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 lists 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 problems specific to their situation and not covered by any of the case below, they can do so by replacing the OSDM namespace with custom namespace starting with an X_ followed by an unique identifier for the provider (ex: X_NVS_NOMEAL).

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 “PARAMETER_NOT_SUPPORTED”.
• If the parameter is optional, return a response including a warning indicating that the optional request parameter was ignored.