Errors and Warnings
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 |
409 |
Conflict |
500 |
Internal server error |
501 |
Not implemented |
503 |
Service unavailable |
Functional errors and the JSON Problem element
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 based on the Problem Details for HTTP APIs RFC RfC-7807 which defines a "problem detail" as 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 title 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.
In order that OSDM implementations also behave consistently in error situations, the following error codes must be supported in case of functional errors by all implementations:
| Functional area | Code | Title |
|---|---|---|
| Places | PLACE_INVALID_CHARACTERS |
Invalid characters in the search string |
| Places | PLACE_NO_RESULTS |
The search did not return any result |
| Trips | TRIP_INVALID_CHARACTERS |
A search criteria value contains invalid value or invalid characters |
| Trips | TRIP_SEARCH_CRITERIA_OUTSIDE_BOUNDARY |
A search criteria lies outside accepted boundaries |
| Trips | TRIP_PLACE_UNKNOWN |
A provided place is not known |
| Trips | TRIP_NO_SEARCH_RESULT |
The search did not return any result |
| Offers | OFFER_TRIP_NOT_FOUND |
The referenced trip cannot be found (expired ?) |
| Offers | OFFER_INVALID_CHARACTERS |
A search criteria value contains invalid value or invalid characters |
| Offers | OFFER_SEARCH_CRITERIA_OUT_OF_BOUNDS |
A search criteria lies outside accepted boundaries |
| Offers | OFFER_PLACE_UNKNOWN |
A provided place is not known |
| Offers | OFFER_NO_RESULTS |
The trip search did not return any result |
| Offers | OFFER_SCHEDULE_MISMATCH |
Schedule mismatch between systems |
| Offers | BOOKING_RESERVATION_OPTION_NOT_AVAILABLE |
The requested reservation option is not available on this vehicle |
| Offers | BOOKING_PASSENGER_PROPERTY_NOT_MODIFIABLE |
Attempted to modify a read-only property (passenger) |
| Offers | BOOKING_OFFERPART_PROPERTY_NOT_MODIFIABLE |
Attempted to modify a read-only property (reservation, ancillary or fare) |
| Booking | BOOKING_OFFER_NOT_FOUND |
Referenced Offer or offer part not found (offer expired ?) |
| Booking | BOOKING_INCOMPATIBLE_OFFER_PART |
Incompatible offer part with the offer |
| Booking | BOOKING_INFORMATION_MISSING |
Missing information |
| Booking | BOOKING_INSUFFICIENT_AVAILABILITY |
Insufficient availability for one of the requested products |
| Booking | BOOKING_PLACE_NOT_AVAILABLE |
The requested place is not available |
| Booking | BOOKING_MODIFY_READ_ONLY_PROPERTY |
Attempted to modify a read-only property |
| Booking | BOOKING_BOOKING_ALREADY_CONFIRMED |
The booking is already confirmed |
| Booking | BOOKING_BOOKING_ALREADY_CANCELLED |
The booking is already cancelled |
| Booking | BOOKING_MODIFICATION_NOT_ALLOWED |
The booking and does not allow modifications |
| Confirm | CONFIRMATION_PARTIAL_SUCCESS |
Partial success |
| Confirm | CONFIRMATION_OPERATION_NOT_SUPPORTED |
Operation not supported on one of the offer parts |
| Confirm | CONFIRMATION_UNKNOWN_ERROR |
Unknown error on provider side |
| Confirm | CONFIRMATION_INFORMATION_MISSING |
Missing information in the booking |
| Confirm | CONFIRMATION_FULFILLMENT_TYPE_NOT_SELECTED |
Fulfillment type not selected |
| Confirm | CONFIRMATION_BOOKING_ALREADY_CONFIRMED |
Booking already confirmed |
| Confirm | CONFIRMATION_BOOKING_ALREADY_FULFILLED |
Booking already fulfilled |
| Confirm | CONFIRMATION_BOOKING_ALREADY_CANCELLED |
Booking already cancelled |
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.
Functional Warnings
In addition to errors, a generic warnings mechanism is used to pass
non-blocking information or event, such as a price difference with the
initially offered price at booking time. As for the errors, Implementers
are required to use the following 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).
A warning message is typically made of a code and a text. Texts are not translated and the expected language there should be 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.
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.