Handling booking requests

Avoid errors and losses by handling booking requests properly.

Overview

It's important to design your booking request workflow to be tolerant of network issues. Don't 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, the traveler's booking may still have been charged and confirmed within our systems. The infrastructure issue could be:

• The network connection is lost (no response returned).
• Server-side error (HTTP Code 500 or 503) is returned .
• A bad network gateway is observed (HTTP Code 502 is returned).
• Network gateway timeout is observed (HTTP Code 504 is returned).
• A response is not following the Rapid API documentation (a key element is missing in the message).
• A response is not in JSON format (for example, a response message is in HTML).
• 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 our call center agents for further support.

Recommended procedure

Always send affiliate_reference_id

Generate a unique affiliate_reference_id for each booking. If resending the same request details (such as 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

The Rapid API connects to external systems to make reservations in real-time. Dependent systems include hotel reservation or reception systems, credit card processors, or fraud detection 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. To cover a degradation scenario, retry the retrieval for 30 minutes before following up with us 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 transaction logs 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.

More error handling guidelines.

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