Common error responses

Our API services share the following common error codes, messages, and response formats. Refer to our individual documentation pages to review error responses that are unique to each service.

Rapid error handling recommendations

Error handling logic

• Platforms and partners should ensure that a Shop and Book error handling logic is in place to handle Rapid errors.
• Always use a unique affiliate_reference_id for every booking request, unless specified in the notes below.
• Partners should constantly review and update their error handling logic, especially for booking requests.
• All Rapid responses have a corresponding HTTP code, see below for a list of response HTTP codes.

Connect time out or communication time out

A 90 second API connection time out setting is recommended for Booking requests. Although there is no set recommendation for other APIs, as a time out would not bring financial loss, a similar time out setting should apply. However, some partners may decide to use a smaller connection time out for Shop availability calls.

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 time out settings in place and 120 seconds is the Rapid final time out. 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 time out does not imply that Rapid has timed out. In these cases either an infrastructure service has failed or Rapid is acting as a gateway to another downstream service and sets a time out limit for that service. It is this time out 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 (affiliate_reference_id+email) as the downstream issue may be before the booking was created (e.g. hotel communication, payment server) or after the booking was created (e.g. EPS finance management). Also, check that the Internet connection is stable. A Traceroute command may help identify any connectivity issues.

Handling Booking and Retrieve 5xx errors

A booking error (5xx status) or time out doesn't necessarily mean the booking itself is invalid and this should not be assumed. The error may have occurred after the booking was created. It is therefore recommended to issue an Itinerary Retrieve with affiliate_reference_id+email to check the status of the booking.

Any error returned within 90 seconds does not indicate the final status of the booking. Typically, most bookings will resolve into a confirmed booking within 13 – 30 seconds, although some may take up to 90 seconds to resolve.

Partners can implement logic to check the status of the booking 3 times within a 90 second period. Most responses will confirm within the first 30 seconds and partners can then confirm the response without waiting the full 90 seconds. If a final response has not been received partners can then retrieve again after 60 seconds and then finally after 90 seconds to validate the final response.

Use a Retrieve API call to double confirm the booking results (HTTP 200 or HTTP 404 response).

Retrieve response returns hold\resume information

Occasionally, after a successful booking, the Itinerary Retrieve response will return response data which looks as if it is for a hold/resume booking. So, rather than the expected booking information (rooms, cancellation penalties, etc.), the response will just have the tokens necessary for a hold/resume situation.

Example response:

{
  "itinerary_id": "2667552437552",
  "links": [
    {
      "rel": "retrieve",
      "method": "GET",
      "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
    },
    {
      "rel": "resume",
      "method": "PUT",
      "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
    },
    {
      "rel": "cancel",
      "method": "DELETE",
      "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
    }
  ]
}

The reason is that the booking, 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.

Error breakdown with multiple-level structure

The API response might break an error down into multiple levels where a single level error could not explain all details. Iterating the information over all levels will help clarify and troubleshoot the error better.

Example response:

{
    "type": "invalid_input",
    "message": "An invalid request was sent in, please check the nested errors for details.",
    "errors": [
        {
            "type": "duplicate_itinerary",
            "message": "An itinerary already exists with this affiliate reference id.",
            "fields": [
                {
                    "name": "affiliate_reference_id",
                    "type": "body",
                    "value": "XXXXXX"
                }
            ]
        }
    ]
}

HTTP response codes

400 - Bad Request

Returns if your request was malformed or contained improper values.

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 the body. So, body.email would indicate the email parameter for the body of the header.

Note: The Book header rooms array must have the same number of entries as the rooms requested in the Availability call.

A 400 Bad Request error labeled "Tomcat Exception Report" is returned when the request parameters are overly large, most often on the Property Content and Get Availability APIs. To avoid this error, reduce the number of properties or remove unnecessary parameters from the request.

Example responses:

Unsupported languages:

{
  "type": "invalid_input",
  "message": "An invalid request was sent in, please check the nested errors for details.",
  "errors": [
    {
      "type": "language.not_supported",
      "message": "Language is not supported. Supported languages are: [de-DE, en-US, es-ES, es-MX, fr-FR, id-ID, it-IT, ja-JP, ko-KR, pt-BR, zh-CN]",
      "fields": [
        {
          "name": "language",
          "type": "querystring",
          "value": "xx-XX"
        }
      ]
    },
    {
      "type": "filter.mismatch",
      "message": "Existing booking is expedia_collect, this cannot be changed",
      "fields": [
        {
          "name": "filter",
          "type": "querystring",
          "value": "property_collect"
        }
      ]
    }
  ]
}

Missing version value:

{
  "type": "version.required",
  "message": "You have not specified a version, the supported versions are: [1, 2]",
  "fields": [
    {
      "name": "version",
      "type": "path",
      "value": "missing"
    }
  ]
}

Invalid version value:

{
  "type": "version.unsupported",
  "message": "You have requested a version that is not supported, supported versions are: [1, 2]",
  "fields": [
    {
      "name": "version",
      "type": "path",
      "value": "3"
    }
  ]
}

401 - Unauthorized

Returns if your HTTP authorization header was not found or could not be parsed. Each request to any of Rapid's API services must include the unsalted SHA-512 hash of the concatenation of your API Key + shared secret + UNIX timestamp in seconds. Refer to our signature authorization page for full details.

Example 401 unauthorized response:

{
  "type": "request_unauthenticated",
  "message": "Data required to authenticate your request is missing. Ensure that your request follows the guidelines in our documentation.",
  "fields": [
     {
       "name": "apikey",
       "type": "header",
       "value": "jaj3982k239dka328e"
     },
     {
       "name": "signature",
       "type": "header",
       "value": "129d75332614a5bdbe0c7eb540e95a65f9d85a5b53dabb38d19b37fad6312a2bd25c12ee5a82831d55112087e1b"
     },
     {
       "name": "timestamp",
       "type": "header",
       "value": 198284729
     },
     {
       "name": "servertimestamp",
       "type": "server",
       "value": 198284729
     }
  ]
}

403 - Forbidden

Returns when your HTTP authorization header is valid but you are not permitted to access the requested resource.

Example 403 forbidden response:

{
  "type": "request_unauthorized",
  "message": "Your request could not be authorized."
}

404 - Not found

Returns if the requested API resource could not be found. Check your request URL against our documented examples.

The Geography API and Content API also use 404 responses to indicate when requested geography- or content-specific files or resources cannot be located. Refer to their respective documentation pages for full examples.

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 parameters were valid so make sure that the Retrieve affiliate_reference_id, email, and/or itinerary number are correct. In addition, if the Retrieve API call was made less than 90 seconds from the Booking call then try the retrieve again, making sure it is more than 90 seconds after the Booking call.

Example response:

{
    "type": "resource.not_found",
    "message": "The requested resource could not be found."
}

409 - Price mismatch

Many properties and chains use dynamic pricing or what is also called “time-based pricing”. This means that pricing varies based on supply and demand algorithms. Expedia Group receives updated rates from properties multiple times per second which means that rates change frequently.

It is important to note that this is typically the choice of the property rather than EPS. Additionally, because there is caching at multiple levels for rates/availability, including at the partner level, there can be several layers of latency in any booking.

A price mismatch (PMM) is an expected situation and can occur for a number of reasons including degradation of systems or systems not reflecting updated prices entered by properties. Partners should monitor the frequency of these events and contact EPS Support should the rate increase suddenly or hit a threshold.

If a PMM has occurred for multiple properties/rooms at the same time, then please check for potential Rapid degradation.

If a PMM is returned for the same rate/room over a long period, then it is probably due to incorrect loading of rates by the property. Please contact EPS Technical Support to check.

To recover from a PMM, make the Price Check API call again to obtain a new Booking URL token. You can then use the same affiliate_reference_id in the booking call.

Example response:

{
  "type": "price_mismatch",
  "message": "Payment amount did not match current price, please check price and try again.",
  "fields": [
    {
      "name": "payments.amount",
      "type": "body",
      "value": "100.00"
    },
    {
      "name": "price.amount",
      "type": "body",
      "value": "120.00"
    }
  ]
}

410 - Gone or sold out

Returns if the Rapid link being followed has expired or the room(s) requested are no longer available.

Many hotel chains and properties have direct communications links with Expedia Group. Synchronous communication is an interactive interchange which takes place in real time between Expedia Group and the properties/chains.

Synchronous communication booking is when the property or chain provides EPS with their room inventory (availability and price), which EPS manages, and subsequent Shop Availability and Price Check calls are made against this data. Then, at the time of booking, a synchronous booking call is made to the property to book the room(s). This error occurs when there is insufficient inventory for the room(s) selected. If it is found that inventory is insufficient, Rapid will return the code 410 error message.

This may be a temporary situation and a retry might find the rooms available. Wait 90 seconds then check the status of the booking with a Retrieve request using the same affiliate_reference_id that was sent with the booking. If no booking is found, users may have to choose another property/room/rate/date combination.

The sold out error messages may also occur if the connection to the property is degraded and so Rapid has no indication of the true availability and will therefore present a sold out error message.

Example response:

Link expired:

{
  "type": "link.expired",
  "message": "The link you followed has expired. Please request a new link."
}

Sold out:

"type": "rooms_unavailable",
"message": "One or more requested rooms are unavailable."

426 - Upgrade required

Returns if the request did not use TLS (supersedes SSL).

Example response:

{
  "type": "upgrade_required",
  "message": "This service requires the use of TLS."
}

429 - Rate limit error

Note: If you receive an error for too many requests, please wait for at least 5 minutes before trying a corrected request. Retrying more frequently will cause repeated failures due to cache timing.

A 429 status code is returned when request counts exceed a rate limit. Every request can be subjected to two different rate limits: those where an integration is sending requests at a rate above the limit and those where the Expedia Group servers are experiencing load above the limit.

When a partner makes an Expedia Group API request, the receiving server checks if the request count is within the limit. If the request count is within the limit, the request goes through and the count is increased for the client. If the client request count exceeds the limit, the server will return a response with an HTTP 429 (too many requests) status code.

The server can optionally include a Rate-Limit-Day-Reset and Rate-Limit-Minute-Reset header. This indicates how long you should wait before sending your next request. They are the timestamps when the next tumble will occur, in microseconds (not milliseconds).

For example, when converted to a date/time, the value '15489792000000' results in Friday, February 1, 2019 12:00:00 AM (UTC).

Example response:

HTTP/1.1 429 Too Many Requests
Connection →keep-alive
Content-Length →106
Date →Fri, 01 Feb 2019 06:20:51 GMT
Rate-Limit-Day-Remaining →18
Rate-Limit-Day-Reset →1548979200000
Rate-Limit-Minute-Remaining →0
Rate-Limit-Minute-Reset →1549002000000
Rate-Limit-Reduction-Status →inactive
Server →EAN
Transaction-Id →003224d2-1407-42fe-8bf8-6d74226e7f00

500 - Internal server error

Returns for an error within Rapid's 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 affiliate_reference_id.

Rapid responds with HTTP 500 when it has detected an issue but cannot be more specific on what the exact problem is. All partners should expect some code 500 responses in their Rapid usage from time-to-time.

An HTTP 500 error can also occur when an unsupported point of sale is being used, such as Syria.

If you received the error in an API response other than a Create Booking or Cancel Booking, and there is no known degradation, retry your request at a later time. The response may include a Retry-After header to indicate the minimum delay (in seconds) before attempting again.

If you received the error in the API response when creating a booking:

• Wait 90 seconds then check the status of the booking with a Retrieve request using the same affiliate_reference_id that was sent with the booking.
• If no booking is found or you continue to receive the 500 error, re-try the booking at a later time.

If you received the error in the API response when Cancelling a booking:

• Wait 90 seconds then check the status of the booking with an Itinerary Retrieve request using the known itinerary_id.
• If the booking is not cancelled or you continue to receive the 500 error, retry the Cancellation request at a later time.

Example responses:

{
  "type": "unknown_internal_error",
  "message": "An internal server error has occurred."
}

{
  "type": "internal_error",
  "message": "An internal server error has occurred. Please discard any previously received results in this pagination and restart the pagination from the beginning."
}

503 - Service unavailable

The HTTP 503 error is generally temporary and indicates that Rapid, or a downstream service, is currently unable to handle the request. There are a number of possible reasons for this, from a temporary overload to the connection to the property being lost.

If you received the error in an API response other than a Create Booking or Cancel Booking, and there is no known degradation, retry your request at a later time. The response may include a Retry-After header to indicate the minimum delay (in seconds) before attempting again.

If you received the error in the API response when Creating a booking:

• The booking link from your previous Price Check response expires after a short period. If you receive an HTTP 503 error upon your first attempt, the link has likely expired. Obtain a new link and attempt your booking again.
• If you get a 503 on the second attempt, wait 90 seconds then check the status of the booking with a Retrieve request using the same affiliate_reference_id that was sent with the booking.
• If no booking was found or you continue to receive the 503 error, re-try the booking at a later time.

If you received the error in the API response when cancelling a booking:

• Wait 90 seconds then check the status of the booking with an Itinerary Retrieve request using the known itinerary_id.
• If the booking is not cancelled or you continue to receive the 503 error, retry the Cancellation request at a later time.

Example response:

{
  "type": "service_unavailable",
  "message": "This service is currently unavailable."
}

504 - Gateway time out

The HTTP 504 error is not usually from Rapid but rather comes from the cloud or edge infrastructure and indicates that an item in the network infrastructure (such as the load balancer) failed during the transaction. It is generally a temporary event.

Please note that the time out may happen before itinerary creation or after, so always check to see if the itinerary was created or not.

The HTTP 504 (and 502) error responses are in HTML format rather than the Rapid JSON type/message object pair. This is another indication that these errors are not generated by Rapid.

Example response:

<html>
<head><title>504 Gateway Time-out</title></head>
<body>
<center><h1>504 Gateway Time-out</h1></center>
</body>
</html>

Threshold rate of error responses

In order to establish their own threshold values, partners should measure the daily rate of the following response codes: 409, 410, 500, 503, and 504. They should contact EPS Support if the threshold is breached.

EPS doesn't have any set threshold values as it really depends on the marketplace that partners are in and sell to as well as other factors. A knowledge of the marketplace is essential in determining why some error responses occur. Guidance is to expect up to 5-6% of booking calls to fail with a code 50xx error over a daily or weekly period.

Over time, partners should be able to calculate their own threshold values. Partners 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.

Logs

If EPS asks for the request/response logs, please try to 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 as well as 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 of whether the Booking call worked or failed.

Please include the full JSON request and response. A JSON string must be double-quoted, so it is not necessary to include the back-slash escape character in front of the double-quote character.

Only use the back-slash escape character in front of a double quote when you require the double quote to be part of the string.

Example response:

"spokenwords": "He said \"hello world\""

Please do not put the logs into PDF format. EPS Support and developers sometimes copy/paste log data into their internal tools, and PDF format adds unnecessary line feed characters to the data.

Appendix

function create_booking(affiliate_reference_id){
  ### make API request to create booking ###
  book_resp = rapid_book_req(affiliate_reference_id, timeout = 90seconds, hold = false)
  ### Retrieve is always required to confirm final status of bookings, to avoid duplicate requests for the last inventory ###
  retrieve_booking(book_resp.retrieve_link, affiliate_reference_id, book_resp.status_code, book_resp.req_timestamp) }

function retrieve_booking(retrieve_link, affiliate_reference_id, book_resp_status_code, rapid_book_req_time) {
  ### display the pending booking message to customers ###
  booking_final_status = "pending"
  ### always use Retrieve link when it returned in booking response ###
   if (retrieve_link == null) {
       retrieve_link = "/rapid_path?XXXXXX&affiliate_reference_id=" + affiliate_reference_id }
       ### confirm the final status of bookings ###
      while (booking_final_status not in ("booked", “canceled”, "manualFollowup", "failed")) 
        ### make API request to retrieve booking ###
      retrieve_resp = retrieve_resquest(retrieve_link) 
      ### a complete Retrieve returns room level Expedia confirmation ID ###
      if (retrieve_resp.rooms.[].confirmation_id is not null) {
          booking_final_status = retrieve_resp.rooms.[].status }
      ### retry Retrieve to monitor booking updates if 90 seconds have not elapsed yet OR system error returned ###
      elseif (currentTime - rapid_book_req_time <= 90seconds) or (retrieve_resp.status_code not in (404, 200)) {
          continue }
      ### retry Retrieve for incomplete booking result or make manual follow-ups after 11 minutes ### 
      elseif (book_resp_status_code in (200, 201, 202, 204)) or (retrieve_resp.itinerary_id is not null) {
          if (currentTime - rapid_book_req_time <= 11minutes) {
            continue } else { booking_final_status = "manualFollowup" } 
      ### retry booking request with the same affiliate reference id value to cover the booking ###
      elseif (booking_retries <= 2) {
          create_booking(affiliate_reference_id) } 
      ### the booking is failed only when the above actions have all been taken ###
      else {
booking_final_status = "failed" }}}