Error Handling

1 Error Responses to SiteConnect
- 1.1 Sample Error Response
- 1.2 OTA Error Warning Types (EWT)
- 1.3 OTA Error Codes (ERR)
  - 1.3.1 Error Codes - General
  - 1.3.2 Error Codes - Updates
2 Error Responses from SiteConnect

Error Responses to SiteConnect

Errors MUST be returned within a 'SOAP Envelope' and use the defined response message container depending on the message being responded to. See the relevant parts of our specification within the Retrieve Rooms API and Inventory and Rate API sections for more information about each error response message.

If the error is specifically related to application-level errors, do not respond to any other error types (HTTP, etc.). If you have server-level issues, then it is OK to respond with HTTP standard error codes.

It is expected that your booking channel has a robust error handling process in place. This includes a queuing mechanism and a robust retry strategy.

An error response must contain a short error description to assist our support teams.

Sample Error Response

<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header/>
	<SOAP-ENV:Body>
		<OTA_HotelAvailNotifRS
			xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="9a40291f-24fa-410d-b1c2-b64efab47da4" TimeStamp="2023-04-28T20:46:53+10:00" Version="1.0">
			<Errors>
				<Error Type="6" Code="392">Hotel not found for HotelCode=XXXXXX</Error>
			</Errors>
		</OTA_HotelAvailNotifRS>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

See the list of mandatory Error Responses to SiteConnect here.

OTA Error Warning Types (EWT)

SiteConnect recommends using the following OTA error types from OTA Error Warning Type (EWT)

Error Type Code	Error Name	Error Reason

Error Type Code	Error Name	Error Reason
1	Unknown	Indicates an unknown error.
2	No implementation	Indicates that the target business system has no implementation for the intended request.
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.
5	Authentication timeout	Indicates that the security credentials in the message have expired.
6	Authorization	Indicates the message lacks adequate security credentials.
7	Protocol violation	Indicates that a request was sent within a message exchange that does not align to the message.
8	Transaction model	Indicates that the target business system does not support the intended transaction-oriented operation.
9	Authentical model	Indicates the type of authentication requested is not recognized.
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.
11	Advisory
12	Processing exception	Indicates that during processing of the request that a not further defined exception occurred.
13	Application error	Indicates that an involved backend application returned an error or warning, which is passed back in the response message.

OTA Error Codes (ERR)

SiteConnect recommends using the following OTA error codes from OTA Error Codes (ERR)

Error Codes - General

These are recommended Error Codes to be returned for general errors:

Error Code	Error Name	Error Description

Error Code	Error Name	Error Description
187	System currently unavailable	`EXPLAIN REASON FOR FAILURE`
448	System error	`Invalid Username and/or Password`
450	Unable to process	`EXPLAIN REASON FOR FAILURE`

Error Codes - Updates

These are recommended Error Codes to be returned for update errors:

Error Code	Error Name	Error Description

Error Code	Error Name	Error Description
137	Adult occupancy mismatch	`Invalid included occupancy`
249	Invalid rate code	`Rate code not found for this hotel`
321	Required field missing	`EXPLAIN REASON FOR FAILURE`
375	Hotel not active	`EXPLAIN REASON FOR FAILURE`
392	Invalid hotel code	`Hotel not found for HotelCode=XXXXXX`
397	Invalid number of adults	`Invalid number of adults`
402	Invalid room type	`Room type code not found for this hotel`
436	Rate does not exist	`EXPLAIN REASON FOR FAILURE`
783	Room or rate not found	`Combination of room code and rate code not found for this hotel`
842	Rate not loaded	`EXPLAIN REASON FOR FAILURE`

Error Responses from SiteConnect

When contacting our Application Operations team, provide as much information as possible in relation to the problematic request(s). This must at the very least be the EchoToken and TimeStamp related to the request. Where possible, the actual redacted request that was made to SiteConnect will allow the quickest turn around time.

If the response contains an OTA message with an 'Error' element then the reservation can not be processed because some data is invalid. This could be, for example, if required data is missing or if the credentials/hotel code are incorrect and the message will not process until the error is fixed. If the error is that a required element or attributes are missing, the implementation will need to be adjusted to send the required data. If the error is to do with credentials, check that the correct username/password is sent. If the error is an invalid hotel code, contact the hotel to make sure they have the correct hotel code configured in SiteMinder.

Sample Error Response

<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header/>
	<SOAP-ENV:Body>
		<OTA_HotelResNotifRS
			xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="8c836193-ef3d-43b9-835a-19f8ffa7282a" TimeStamp="2023-04-28T10:35:29+00:00" Version="1.0">
			<Errors>
				<Error Type="10">Node CreateDateTime must exist</Error>
			</Errors>
		</OTA_HotelResNotifRS>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

See more samples of Error Responses from SiteConnect here.

OTA Error Warning Types (EWT)

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

Error Code	Error Name	Error Reason

Error Code	Error Name	Error Reason
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.
12	Processing exception	Indicates that during processing of the request that a not further defined exception occurred.

Handling HTTP 500 Error Responses on SiteConnect

If the response is a HTTP error response code in the 500 range then it is expected that the connecting OTA will implement a retry strategy until they are successfully delivered or a pre-defined timeout period is reached, for example, 30 minutes. Below we've provided a table that outlines the expected behaviour for each 500 range error. In the case that an update cannot be delivered within the timeout period, a case should be raised with our Application Operations team.

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 SiteConnect has been configured correctly.