Error Handling

Your PMS/RMS should have a strong error handling system that can queue and resend errors. Additionally, you need to inform hoteliers about any errors that impact the synchronization of their data through pmsXchange.

Application Level

If the response from pmsXchange contains an OTA RS message with an 'Error' element, it indicates that the update cannot be processed due to invalid data. Here are some common application-level error scenarios:

Missing Required Elements or Attributes: Adjust your implementation to ensure all required data is sent.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelAvailNotifRS Version="1.0" TimeStamp="2025-10-25T01:32:55+00:00" EchoToken="TEST9BA23FF4-2EE4-11EF-2426-09173F13E4C5" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="10">The content of element "AvailStatusMessages" is not complete. One of "AvailStatusMessage" is expected</Error>
         </Errors>
      </OTA_HotelAvailNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelAvailNotifRS Version="1.0" TimeStamp="2025-10-25T01:33:55+00:00" EchoToken="TEST9BA23FF4-2EE4-11EF-2426-09173F13E4C5" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="3" Code="450">The HotelCode length must be equal to or greater than 1</Error>
         </Errors>
      </OTA_HotelAvailNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Incorrect Credentials: Verify that the correct username and password are set in your PMS/CRS/RMS. If you believe the details are accurate, confirm them with our PMS Support team.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelAvailNotifRS Version="1.0" TimeStamp="2025-10-25T01:29:05+00:00" EchoToken="TEST9BA23FF4-2EE4-11EF-2426-09173F13E4C5" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="4">Authentication failed - PMS received request with invalid username/password</Error>
         </Errors>
      </OTA_HotelAvailNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Invalid Hotel Code: Ensure the Hotel Code is entered correctly in your PMS. If you think the code is correct, contact our PMS Support team to verify it.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <OTA_HotelAvailNotifRS Version="1.0" TimeStamp="2025-10-25T01:27:05+00:00" EchoToken="TEST9BA23FF4-2EE4-11EF-2426-09173F13E4C5" xmlns="http://www.opentravel.org/OTA/2003/05">
         <Errors>
            <Error Type="6">PMS is not authorized to access hotel with HotelCode=XXXXX</Error>
         </Errors>
      </OTA_HotelAvailNotifRS>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Below is an outline of the OTA (OpenTravel) standard EWT and ERR codes that will be used alongside the error messages specified in each pmsXchange API response.

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 a required element or attribute, as defined by the schema or agreed upon by trading partners, is missing from the message. In the context of pmsXchange, this error will also be returned if the XML message does not conform to the data type restrictions specified by the XML schema.
12	Processing exception	Indicates that an undefined exception occurred during the processing of the request.

EWT

Error Type

Description

Unknown

Indicates an unknown error.

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.

Authentication

Indicates the message lacks adequate security credentials

Authorization

Indicates the message lacks adequate security credentials

Required field missing

Indicates that a required element or attribute, as defined by the schema or agreed upon by trading partners, is missing from the message. In the context of pmsXchange, this error will also be returned if the XML message does not conform to the data type restrictions specified by the XML schema.

Processing exception

Indicates that an undefined exception occurred during the processing of the request.

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

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

HTTP Server Level

500 Internal Server Error: This usually means the request is malformed or cannot be parsed. Implement a retry strategy and flag the message for your development team to review.
503 Server Unavailable: This typically indicates that we are performing maintenance on the pmsXchange service. Your implementation should retry any failed messages as part of a retry strategy.

Handling HTTP 500 Error Responses

Error Code	Error Reason	Suggested Handling Method
500 - Internal Server Error	A generic error message is provided when an unexpected condition is encountered and no specific message applies.	Implement a retry strategy to determine if the 500 error is a random occurrence. Once you've established that the error is not random, verify the validity of the request. If you still believe the request is valid, contact our Application Operations team for assistance.
501 - Not Implemented	The server does not recognize the request method or lacks the ability to fulfill the request, often implying that future availability may be expected (e.g., a new feature in the web-service API).	Fail the request and check whether the request is currently supported by the web service associated with this endpoint.
502 - Bad Gateway	The server acts as a gateway or proxy and receives an invalid response from the upstream server.	For this, implement a retry strategy that accommodates high load situations. We suggest using an "Exponential Backoff" strategy, as follows: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout. We recommend a timeout of at least 30 minutes from the initial request. Once the timeout is reached and the message has failed, please contact our Application Operations team for assistance.
503 - Service Unavailable	The server is currently unavailable due to being overloaded or undergoing maintenance. This condition is typically temporary.	For this, implement a retry strategy that accommodates high load situations. We suggest using an "Exponential Backoff" strategy, as follows: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout. We recommend a timeout of at least 30 minutes from the initial request. Once the timeout is reached and the message has failed, please contact our Application Operations team for assistance.
504 - Gateway Timeout	The server, acting as a gateway or proxy, did not receive a timely response from the upstream server.	For this, implement a retry strategy that accommodates high load situations. We suggest using an "Exponential Backoff" strategy, as follows: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout. We recommend a timeout of at least 30 minutes from the initial request. Once the timeout is reached and the message has failed, please contact our Application Operations team for assistance.
505 - HTTP Version Not Supported	The server does not support the HTTP protocol version specified in the request.	Fail the request and verify that the client making requests to pmsXchange is configured correctly.

Error Code

Error Reason

Suggested Handling Method

500 - Internal Server Error

A generic error message is provided when an unexpected condition is encountered and no specific message applies.

Implement a retry strategy to determine if the 500 error is a random occurrence.

Once you've established that the error is not random, verify the validity of the request. If you still believe the request is valid, contact our Application Operations team for assistance.

501 - Not Implemented

The server does not recognize the request method or lacks the ability to fulfill the request, often implying that future availability may be expected (e.g., a new feature in the web-service API).

Fail the request and check whether the request is currently supported by the web service associated with this endpoint.

502 - Bad Gateway

The server acts as a gateway or proxy and receives an invalid response from the upstream server.

For this, implement a retry strategy that accommodates high load situations. We suggest using an "Exponential Backoff" strategy, as follows:

5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout.

We recommend a timeout of at least 30 minutes from the initial request.

Once the timeout is reached and the message has failed, please contact our Application Operations team for assistance.

503 - Service Unavailable

The server is currently unavailable due to being overloaded or undergoing maintenance. This condition is typically temporary.

For this, implement a retry strategy that accommodates high load situations. We suggest using an "Exponential Backoff" strategy, as follows:

5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout.

We recommend a timeout of at least 30 minutes from the initial request.

Once the timeout is reached and the message has failed, please contact our Application Operations team for assistance.

504 - Gateway Timeout

The server, acting as a gateway or proxy, did not receive a timely response from the upstream server.

For this, implement a retry strategy that accommodates high load situations. We suggest using an "Exponential Backoff" strategy, as follows:

5 seconds → 10 seconds → 20 seconds → 40 seconds → then every minute until a defined timeout.

We recommend a timeout of at least 30 minutes from the initial request.

Once the timeout is reached and the message has failed, please contact our Application Operations team for assistance.

505 - HTTP Version Not Supported

The server does not support the HTTP protocol version specified in the request.

Fail the request and verify that the client making requests to pmsXchange is configured correctly.

Soap Faults

A SOAP fault can be returned in the event of an unexpected error, such as when the XML in a SOAP message cannot be parsed. The SOAP Fault will specify which party is at fault (CLIENT or SERVER).

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">Invalid SOAP message</faultstring>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">Namespace prefix s on Envelope is not defined</faultstring>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Last updated 15 days ago