_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:
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
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:
Functional area | Error 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 |
Booking | BOOKING_VEHICLE_TOO_HEAVY |
A vehicle is too heavy to be transported by car carriage. This relates to the current load of the train or coach, so booking might be possible at another |
Booking | BOOKING_VEHICLE_WEIGHT_MISSING |
A vehicle is not possible without providing the weight of the vehicle |
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.
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:
Functional area | Warning Code | Title |
---|---|---|
Reservation | PLACE_PROPERTY_NOT_RESPECTED |
Place property not respected |
todo | todo |
todo |
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.