Errors and Problems

General HTTP error codes and generic situations

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

Error Code	Description
`400`	Bad request
`401`	Unauthorized
`403`	Forbidden
`404`	Not found
`405`	Method not allowed
`409`	Conflict
`429`	Too many requests
`500`	Internal server error
`501`	Not implemented
`503`	Service unavailable

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

Property	Description	Mandatory
`code`	The `code` property should begin with the code of the error type	yes
`title`	Short, human-readable summary of the problem type which should not change from occurrence to occurrence of the problem.	yes
`type`	An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).	yes
`detail`	Human-readable explanation specific to this occurrence of the problem	no
`status`	The HTTP status code generated by the origin server for this occurrence of the problem.	no
		no

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 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:

Problem code	Description
`RESOURCE_NOT_FOUND`	The requested (sub) resource could not be found. Could be deleted or expired
`OPERATION_NOT_PERMITTED`	Trying to perform an operation that is not permitted.
`NO_RESULTS`	The search did not return any result
`VALIDATION_ERROR`	The request contains incorrect information
`MALFORMED_REQUEST`	The request does not match the OSDM specification. Possible version mismatch
`MISSING_INFORMATION`	Missing information. Provide the mandatory information and try again
`PARAMETER_NOT_SUPPORTED`	A given request parameter is not supported and ignored while handling the request
`INVALID_INPUT`	Provided input is invalid.
`UNKNOWN_ERROR`	Unexpected or unspecified error occurred
`PROPERTY_SUBSTITUTED`	Requested property is not available and is substituted. Check the response for the substitute
`PARTIAL_SUCCESS`	The request could not be fully processed and is partially processed
`SERVICE_UNAVAILABLE`	The service is currently not available
`UNAUTHORIZED`	Client is no authorized

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 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).

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.