This document provides recommendation for Partners when they build an effective and efficient error handling logic to their Rapid trading application. It also attempts to explain why errors happen so that Partners can better anticipate what may be happening to cause the errors.
In this document, the term ARID means "Affiliate Reference ID" from the Booking request header
Error Handling logic.
Platforms and Partner should ensure that a Book error handling logic is in place to handle Rapid errors.
Always, always use a unique Affiliate Reference ID (ARID) for every unique booking request, unless specified in the notes below.
Partners should constantly review and update their error handling logic, especially for booking requests. A great start to this is to review the following Rapid documents:
- Handling Booking Requests:
- Common Error Responses:
- Rapid Error Handling matrix - suggested actions for possible Rapid Errors:
- The response information from each API request. For example:
Any Rapid response has a corresponding HTTP code – see the relevant API document in Rapid Developer Hub for the possible list of response HTTP codes.
Very likely an API Connection timeout. EPS Partner:Connect recommends using a 90 second API connection timeout setting for BOOKING requests. We don’t have any recommendations for other APIs as a timeout would not bring financial loss, but a similar timeout setting would apply.
If a Partner hasn't received a response in 120 seconds, they are never going to receive a response. This is because EPS Rapid has its own timeout settings in place and 120 seconds is the Rapid final timeout. After that Rapid will issue a 5xx error.
In some cases Rapid doesn’t support the "HTTP Expect: 100-Continue" process. Partners may experience connection issues when trying to connect servers with the process, especially in the cURL, C#/.NET, and some other coding languages that follow the process by default.
Note: HTTP 504 Gateway Timeout does not imply that Rapid has timed-out. In these cases either a infrastructure service has timed out or Rapid is acting as a Gateway to another downstream service and sets a timeout limit for that service. It is this timeout which has triggered and EPS needs to report it as a 504. If the 504 happens for a booking call, please check to see if the booking was created or not using Itinerary Retrieve (ARID+email) as the downstream transaction may be before the booking create (eg: hotel communication, payment server) or after the booking was created (eg: EPS finance management.
Booking and Retrieve Errors
Please do not assume that a booking error or timeout means the booking is invalid. The error may have occurred after the booking was created. It is recommended to issue an Itinerary Retrieve with ARID+email to check the status of the booking.
Any error returned within 90 seconds may not indicate the final status of the booking. Wait for 90 seconds and use a Retrieve API call to double confirm the booking results (HTTP 200 or HTTP 404 response).
Retrieve response returns Hold\Resume information
In some very infrequent cases, after a successful booking the Itinerary Retrieve response will return response data as if for a Hold/Resume booking. So, rather than the expected booking information (rooms, cancel penalties, etc), the response will just have the tokens necessary for a Hold/Resume situation:
The reason is that the booking, for a number of reasons, though perfectly valid, still has a pending flag on it. This will eventually clear, usually within minutes, and so the Itinerary Retrieve requests should be repeated until the booking is completed.
Code 400 Bad Request:
"message": "An invalid request was sent in, please check the nested errors for details.",
The code 400 Bad Request errors indicate an issue with the request booking header. The error response will include the actual error array field in the booking request header which is invalid. The booking header consists of a number of arrays and sub-arrays, such as rooms. and payments.. The overall array is body. So, body.email would indicate the email parameter for the body of the header.
Look out for:
- the rooms. array must have the same number of entries as the rooms requested in the Availability call.
- differences between 2.4 and previous version header arrays. Email and phone were moved from and rooms. array into the body. array. For example:
Rapid 2.3 Booking header showing email & phone details in rooms and payments array
Rapid 2.4 Booking Header showing email & phone details in main body array
"special_request": "Top floor"
"line_1": "555 1st St",
"line_2": "10th Floor",
"line_3": "Unit 12",
"affiliate_metadata": "data_point_1:123|data_point2:This is data.",
"traveler_handling_instructions": "Please use the card provided for payment. Avoid cancelation as this is for a corporate traveler. Contact traveler if any issues."
Code 404 Not Found
"message":"Itinerary was not found with provided request."}
The code 404 after an Itinerary Retrieve indicates that the booking could not be found. If the Retrieve was done because of a booking error, it shows that the booking was not created. However, partners need to ensure that the Itinerary Retrieve API request parameter were valid (ie: ARID + email; itinerary number + email). In addition, if the Retrieve API call was done before 90 seconds from the Booking call, then try the retrieve again, making sure it is after 90 seconds from the Booking call.
Code 409 Price Mismatch
"message": "Payment amount did not match current price, please check price and try again.",
There are three main ways that a 409 Price Mismatch (PMM):
- There is a problem with the Rapid API pricing engine, usually when a degradation is happening.
- There is a Price Mismatch due to business conditions. Hotels, certainly many larger chains, apply rate price algorithms - also known as dynamic pricing. So, they may ask EPS to load their inventory at price A but by the time of the booking, when a synchronous check is made, their price may have changed to price B. EPS attempts to manage these situations by ensuring a price-check is done just before the booking call and also by making the booking token expire quickly (getting HTTP 503) and so forcing another price check.
- A number of hotels load Expedia inventory with bad prices. A study was done by EPS development and it appears that certain properties are chronic PMM offenders.
Synchronous communication booking is when the hotel or chain provide EPS their room inventory (availability and price), which EPS manages. But the hotel is also managing the same inventory and so there might be a mismatch in the EPS-managed inventory and the hotel-managed inventory. At the time of the booking, EPS makes a synchronous call to the property to check the actual inventory. This is why sometimes there might be sold-out responses from the booking request but also price mismatch due to dynamic pricing.
So, a sold-out or PMM is an expected situation. Partners should monitor the rate of these events and contact EPS Support should the rate increase suddenly or hits a threshold.
To recover from a PMM, issue the Price-Check API call again to obtain a new Booking URL token. You can then use the same ARID in the booking call.
Code 410 Sold Out (from Booking request)
"message": "One or more requested rooms are unavailable."
The property is probably using synchronous communication with EPS, and so the property inventory is being managed by both EPS and by the property at the same time. This could cause a mismatch between the two inventories. This might be a temporary situation and a retry might find the rooms available. Please see synchronous communications in 409 Price Mismatch.
Code 500 Internal server error
"message": "An internal server error has occurred."
Indicates an error within EPS Rapid API or upstream systems. Follow the instructions in the message field if a specific action is given, otherwise, simply try your request again, with the same ARID.
The "Internet Assigned Numbers Authority (IANA)", who maintain HTTP code definition, has defined HTTP 500 as:
500 Internal Server Error
A generic error message, given when an unexpected condition was encountered, and no more specific message is suitable
Rapid responds with HTTP 500 when it has detected an issue but could not be more specific on what the exact problem is.
A booking is a complicated transaction with multiple different applications, services and environments involved; from payment engines to hotel inventory applications It is inevitable that a system, communication or network error will occur at some time. When Rapid gets an error and can't determine the cause, it will issue a HTTP code 500 error. Partners and Platforms should expect some code 500 responses in their Rapid usage from time to time and should also be able to cope with them.
A HTTP 500 error may also occur when an unsupported POS is being used, such as Syria.
Hopefully Partners are using a unique Affiliate Reference ID (ARID) for their bookings. If they tried the book API call again, as the Rapid Common Error document suggests, then it will be able to check if the booking was created (you will get a code 400 "An itinerary already exists with this affiliate reference id" response, or if there is a more serious error, or it may create the booking as intended.
503 Service Unavailable
The HTTP 503 Service Unavailable error will generally be temporary, and indicates that Rapid or a downstream service is currently unable to handle the request. There are a number of reasons for this, from temporary overload to the server actually refusing the connection. The response may include a retry-After header for a suggested wait time before retrying the request again.
Normally, just retry the same API call which resulted in the API, though if it happened due to a Book request then a Itinerary Retrieve (ARID+email) may be sent to check for the reservation status.
However, a 503 can also be returned when the Book token from the previous price-check has expired. See Important Notes in https://developer.expediapartnersolutions.com/documentation/rapid-booking-docs-2-4/. In this case you will need to obtain a new valid token and retry the Book request.
504 Gateway Timeout
These HTTP 504 Gateway Timeouts are not generally from Rapid but come from the cloud or edge infrastructure and indicate that an item in the network infrastructure (load balancer, usually) failed during the transaction. It is a temporary event.
Please note that the timeout may happen before itinerary creation or afterwards, so always check to see if the itinerary was created or not.
Please review the Rapid Handling Booking Requests document on how to handle these timeouts. https://developer.expediapartnersolutions.com/reference/handling-booking-requests
Threshold rate of error responses
Partners should measure the daily rate of certain errors, such as 409, 500, and 504 and establish their own threshold values for the errors. They should contact EPS Support if the threshold is reached.
EPS don't have any "exact" threshold values as it really depends on the marketplace that Partners are in and sell to and also depends on other factors. For instance, at the beginning of July 2020 there was a rise in code 409 PMM for Spanish EUR package bookings, presumably as Spanish hotels adjusted their prices due to UK and other country COVID-19 quarantine rules being applied for tourists returning from Spain.
A rule of thumb is to expect up to 5-6% of booking calls failing with code 500/504 error over a daily or weekly period.
Over time Partners should be able to calculate their own threshold values. And they shouldn’t just look for a sudden daily increase. Even if a threshold of 5 per day is set, getting two 500 errors within 5 minutes of each other, for example, may be a cause to check with EPS Support.
If EPS asks for the request/response logs, please try and provide the following:
- The “Transaction-Id” value in the API response header. This is vital for deep dive investigations.
- Both API request and response logs. The Request logs should include the FULL endpoint URL used. The response logs should include the HTTP code returned, the FULL response data and any returned headers.
- Availability API request with &point_of_sale parameter, plus Availability response – this will allow EPS Support to identify the Rapid account and profile being used.
- Booking API request header and Authorisation header (with APIKey, Signature and timestamp) for each booking request.
- The Booking request URL and token in the request logs
- The Itinerary Retrieve issued after a booking API call, regardless as to whether the Booking call worked or failed.
Please include the full JSON request and response.
- The recommendation for Booking request errors is to always use the Itinerary Retrieve (with ARID+email) to check on the actual status of the booking.
- HTTP code 500 and 504 are usually temporary states and the recommendation is to check the status with Itinerary Retrieve and then retry the failing API call.
- Please be very careful about changing ARID after a booking error. By using the same ARID when retrying the booking call allows Rapid to check if there is already a booking with that ARID (HTTP 404) response and so prevent duplicate bookings.
- Please check all response headers. For instance, the response for a HTTP code 503 may include a Retry-After header to indicate the minimum delay (in seconds) before attempting again.