Error Handling

1 General Overview of Error Handling
2 Application Level Error Handling
- 2.1 OTA Error Warning Types
- 2.2 OTA Error Codes
3 Handling HTTP 500 Error Responses on pmsXchange

General Overview of Error Handling

Expectations for Error Handling over pmsXchange

It is expected that your PMS/CRS/RMS has a robust error handling process as outlined and agreed to in our Integration Requirements. This includes a queuing mechanism and a robust retry strategy. More information in relation to Error Handling is outlined below.

Read the below to make sure you have a good understanding on the requirements for error handling over pmsXchange.

Common Error Handling Scenarios you may encounter over pmsXchange

Application Level

If the response back from pmsXchange contains an OTA RS message with an 'Error' element, then the update can not be processed because some data is invalid. Below are some common application level error scenarios:

Required element or attributes are missing: the implementation will need to be adjusted to send the required data.
Incorrect credentials: check that the correct username/password is set within PMS/CRS/RMS. If details are believed to be correct, confirm correct credentials with our PMS Support team.
Invalid hotel code: make sure the Hotel Code is correctly entered in your PMS. If you believe the Hotel Code is correct, reach out to our PMS Support team to cross check the Hotel Code.

HTTP Server Level

If the error is 500 Internal Server Error, it's likely the request being sent is malformed/cannot be parsed: implement a retry strategy and fail the message for review by your development team.
If the error is 503 Server Unavailable, it's likely we're performing maintenance on the pmsXchange service. The implementation will need to retry failed messages as part of a retry strategy. See the 'Handling HTTP 500 Error Responses' below for more information.

Application Level Error Handling

Below outlines the OTA (OpenTravel) standard EWT and ERR codes that will be used in-conjunction with the error messages outlined in each pmsXchange API.

OTA Error Warning Types

pmsXchange will use the following OTA error types from OTA Error Warning Type (EWT):

EWT	Error Type	Description

EWT	Error Type	Description
1	Unknown	Indicates an unknown error.
3	Biz rule	Indicates that the XML message has passed a low-level validation check, but that the business rules for the request message were not met.
4	Authentication	Indicates the message lacks adequate security credentials
6	Authorization	Indicates the message lacks adequate security credentials
10	Required field missing	Indicates that an element or attribute that is required in by the schema (or required by agreement between trading partners) is missing from the message. For PmsXchange this type will also be returned if the xml message does not meet the restrictions (e.g data types) specified by the xml schema.
12	Processing exception	Indicates that during processing of the request that a not further defined exception occurred.

OTA Error Codes

pmsXchange will use the following OTA error types:

Error Name	Error Description

Error Name	Error Description
Invalid Endpoint	`Authentication failed - PMS does not exist`
Invalid Requestor ID	`Inconsistent PMS codes. PMS 'PMSCODE' does not match RequestorID 'PMSCODEX'`
Invalid Credentials	`Authentication failed - PMS received request with invalid username/password`
Invalid Hotel Code	`PMS is not authorized to access hotel with HotelCode=HOTELCODE`
System error
Unable to process

Handling HTTP 500 Error Responses on pmsXchange

Error Code	Error Reason	Suggested Handling Method

Error Code	Error Reason	Suggested Handling Method
500 - Internal Server Error	A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.	Implement a retry strategy that aims to establish whether the 500 error received is a random event. Once established the error is not a random event (using a retry strategy), verify the request is valid. If you believe the request to be valid, reach out to our Application Operations team.
501 - Not Implemented	The server either does not recognise the request method, or it lacks the ability to fulfil the request. Usually this implies future availability (e.g., a new feature of a web-service API).	Fail request and review whether the request is currently supported by the web service attached to this endpoint.
502 - Bad Gateway	The server was acting as a gateway or proxy and received an invalid response from the upstream server.	For this you should implement a retry strategy that is sympathetic to high load situations. We suggest that you implement an 'Exponential Backoff' strategy (see Exponential Backoff). We'd recommend something like: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout. We recommend at least 30 minutes from the initial request until a timeout is considered. Once the time out is reached and the message has failed, reach out to our Application Operations team.
503 - Service Unavailable	The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.	For this you should implement a retry strategy that is sympathetic to high load situations. We suggest that you implement an 'Exponential Backoff' strategy (see Exponential Backoff). We'd recommend something like: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout. We recommend at least 30 minutes from the initial request until a timeout is considered. Once the time out is reached and the message has failed, reach out to our Application Operations team.
504 - Gateway Timeout	The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.	For this you should implement a retry strategy that is sympathetic to high load situations. We suggest that you implement an 'Exponential Backoff' strategy (see Exponential Backoff). We'd recommend something like: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout. We recommend at least 30 minutes from the initial request until a timeout is considered. Once the time out is reached and the message has failed, reach out to our Application Operations team.
505 - HTTP Version Not Supported	The server does not support the HTTP protocol version used in the request.	Fail the request and ensure that the client making requests to pmsXchange has been configured correctly.