Handling booking requests

It is important to handle booking requests properly in order to avoid errors and losses.

Overview

It is important to design your booking request workflow to be tolerant of network issues. Do not interpret a lack of a response as an indicator of a failed booking. If an infrastructure issue occurs after a reservation request is sent but before the response is received, then your customer's booking may still have been charged and confirmed within Rapid's systems. The infrastructure issue could be:

• The network connection is lost (e.g. no response returned).
• Server-side error is returned (e.g. HTTP Code 500 or 503 is returned).
• A bad network gateway is observed (e.g. HTTP Code 502 is returned).
• Network gateway timeout is observed (e.g. HTTP Code 504 is returned).
• A response is not following the Rapid documentation (e.g. a key element is missing in the response message).
• A response message is not in JSON format (e.g. a response message is in HTML format).
• Other exceptions, errors, unknown behavior, or breaks.

Create Booking request should be followed up with a Retrieve Booking request that includes:

• The original value of affiliate_reference_id and email used in the Create Booking request. OR
• The value of itinerary_id and links.retrieve.href returned in Create Booking response.

Note: Newly created itineraries can sometimes have a short delay between the time of creation and the time that the itinerary can be retrieved. If you receive an error when trying to retrieve an itinerary that was successfully created, or if you receive a response with both itinerary_id and creation_date_time, then please retry the retrieval for 30 minutes before following-up with Rapid call center agents for further support.

Recommended procedure

Always send affiliate_reference_id

Generate a unique affiliate_reference_id  for each customer's booking. If resending the same request details (e.g. due to a failed attempt) the same affiliate_reference_id should be used. This prevents accidental duplicate bookings. When sending a new Create Booking request, the API will not respond until the booking is either confirmed or refused. The majority of responses are returned within a few seconds. However, a small number of bookings can take up to several minutes to process and generate a response.

Monitor bookings that do not resolve quickly

Rapid connects to external systems to make reservations in real-time. The dependent systems could be the different hotels’ reservation systems, front desk reception systems, credit card processor, or fraud detect systems. 98% of bookings can complete the process within ~13 seconds. However, if you do not receive the Booking response after 90 seconds, check the progress of the booking with a Retrieve request, using the same affiliate_reference_id that was sent with the booking. If the reservation is still in progress or if the reservation has failed, you will receive the 404 error "Itinerary was not found with provided request." After receiving this message, you should attempt your booking request again with the same affiliate_reference_id. If the reservation is still being completed, you will see a 400 error with the message "An itinerary already exists with this affiliate reference ID." If this error is returned, you can retrieve the booking again to see if the reservation details are ready to be viewed.

The Retrieve API may return errors or an incomplete response when a reservation is being processed. Retrying the Retrieve Booking call later will recover 99.99% of errors. In order to cover a degradation scenario, please retry the retrieval for 30 minutes before following-up with Rapid call center agents for further support.

Booking disputes

If you encounter any problems with booking due to timeouts, 50x HTTP code errors, or other infrastructure issues, please provide the following logs of Rapid API transactions for troubleshooting:

• The Booking request and response (if available).
• The request and response of the Retrieve Booking that was sent 30 minutes after the last booking attempt.

The log should include the HTTP headers of both the request and response. The response message has a transaction-id header that helps us to identify the Rapid API transaction. You can find more error handling guidelines at at this link.

Log into your Rapid Support account to view user interface example, pseudocode to handle bookings, and integration plan examples.