Error Handling

General Overview of Error Handling

Expectations for Error Handling over SMX

It is expected that your application has a robust error handling process in place. An error response should contain a short description of the error to assist our Support teams in troubleshooting.

Please read the below to make sure you have a good understanding of the requirements for error handling over SMX for PMS.

Application Level Error Handling

Below are the OTA (OpenTravel) standard EWT codes that will be used.

OTA Error Warning Types

SMX for PMS will use the following OTA error types from OTA Error Warning Type (EWT)

EWT	Error Type	Description
2	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 SMX 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 the processing of the request, the process encountered an unexpected condition that prevented it from continuing successfully

Common Error Handling Scenarios

Invalid Web Service URI

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelResNotifRS EchoToken="4528545b-f875-5c77-9205-22631b68f15a" TimeStamp="2018-09-28T01:48:44+00:00" Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="4">Authentication failed - PMS {REQUESTORID} does not exist</Error>
         </Errors>
      </OTA_HotelResNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Solution: Confirm you are sending your messages to the correct web service endpoint for your PMS.

Invalid Username/Password

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelResNotifRS EchoToken="4528545b-f875-5c77-9205-22631b68f15a" TimeStamp="2018-09-28T01:47:17+00:00" Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="4">Authentication failed - PMS {REQUESTORID} received request with invalid username/password</Error>
         </Errors>
      </OTA_HotelResNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Solution: Confirm you are sending your messages to the correct credentials for your PMS/Hotelier.

Invalid RequesterID

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelResNotifRS EchoToken="4528545b-f875-5c77-9205-22631b68f15a" TimeStamp="2018-09-28T01:48:28+00:00" Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="6">Inconsistent PMS codes. PMS '{WS_URI}' does not match RequestorID '{REQUESTORID}'</Error>
         </Errors>
      </OTA_HotelResNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Solution: Confirm you are using the correct RequestorID in your message payload.

Invalid Hotel Code

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelResNotifRS EchoToken="4528545b-f875-5c77-9205-22631b68f15a" TimeStamp="2018-09-28T01:44:44+00:00" Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="6">PMS {REQUESTORID} is not authorized to access hotel with HotelCode={HOTELCODE}</Error>
         </Errors>
      </OTA_HotelResNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Solution: Confirm you are using the correct HotelCode in your message payload.

Required Information Missing

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelResNotifRS EchoToken="4528545b-f875-5c77-9205-22631b68f15a" TimeStamp="2018-09-28T01:45:04+00:00" Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="10">Could not validate the schema: cvc-complex-type.2.4.b: The content of element 'tag0:ResGlobalInfo' is not complete. One of '{"http://www.opentravel.org/OTA/2003/05":BasicPropertyInfo}' is expected.</Error>
         </Errors>
      </OTA_HotelResNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The above shows the response for a reservation missing OTA_HotelResNotifRQ / HotelReservations / HotelReservation / ResGlobalInfo / BasicPropertyInfo @HotelCode

Solution: You will need to adjust your implementation to include the missing information/data.

Handling HTTP 500 Error Responses on SMX

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.	Please 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), please verify the request is valid. If you believe the request to be valid, please 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).	Please 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, please 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, please 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, please 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.	Please fail the request and ensure that the client making requests to SMX has been configured correctly.