From 9956832257b2e138dd44465c5097253e8e6ed376 Mon Sep 17 00:00:00 2001 From: Nicolas Selleslagh Date: Tue, 3 Sep 2024 12:57:23 +0200 Subject: [PATCH] Revert "#627 Moved the offer no result from the error list to the warning list" --- spec/errors-problems.md | 88 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 3 deletions(-) diff --git a/spec/errors-problems.md b/spec/errors-problems.md index 4b9c5a42..8f4040da 100644 --- a/spec/errors-problems.md +++ b/spec/errors-problems.md @@ -89,10 +89,10 @@ Request with invalid input } ``` -## Standardized Functional Errors +## Standardized Technical 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 +following error codes must be supported in case of technical errors by all implementations: | **Problem code** | **Description** | @@ -112,7 +112,49 @@ implementations: | `UNAUTHORIZED` | Client is no authorized | -The list can be extended by an implementor but at least these errors must be +## 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_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 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 @@ -120,6 +162,46 @@ 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. + +```json +"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 | +| Offers | `OFFER_NO_RESULTS` | The trip search did not return any result | +| 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