常见错误响应

我们的 API 服务会共享下列常见错误代码、消息和响应格式。请参考我们的各个文档页面，查看特定于每项服务的错误响应。

Rapid 错误处理建议

错误处理逻辑

• 平台和合作伙伴应确保可以使用选购和预订的错误处理逻辑来处理 Rapid 错误。
• 除非在下面的注释中明确规定，否则每次预订请求都要使用一个独一无二的 affiliate_reference_id。
• 合作伙伴应时常检查和更新其错误处理逻辑，特别是有关预订请求的错误处理逻辑。
• 所有的 Rapid 响应都有相应的 HTTP 代码，请查看下文获取响应的 HTTP 代码列表。

连接超时或通信超时

对于预订请求，建议设置 90 秒的 API 连接超时。对其他 API 虽无设置建议，但由于超时不会带来经济损失，所以应该适用类似的超时设置。然而，一些合作伙伴可以决定是否要对预订房态调用使用较短的连接超时设置。

如果合作伙伴没有在 120 秒内得到响应，那么他们永远也不会得到响应。这是因为 EPS Rapid 有自己的超时设置，120 秒是 Rapid 的最终超时。之后，Rapid 会发出一个 5xx 错误。

在某些情况下，Rapid 不支持 HTTP Expect: 100-Continue 流程。 在尝试使用该流程连接服务器时，合作伙伴可能会遇到连接问题，特别是在使用 cURL、C#/.NET 和其他一些默认遵循该流程的编码语言时。

**注意：**HTTP 504 网关超时并不表示 Rapid 已超时。如果发生这种情况，要么是基础设施服务发生了故障，要么是 Rapid 作为另一个下游服务的网关，并为该服务设置了一个超时限制。正是因为触发了该超时，EPS 才需要将其报告为 504。如果预订调用报告了 504，请检查是否使用行程检索（affiliate_reference_id + 电子邮件）创建了预订，因为下游的问题可能发生在预订创建之前（如酒店通信，付款服务器），也可能发生在预订创建之后（如 EPS 财务管理）。 另外，请检查网络连接是否稳定。Traceroute 命令可能有助于识别连接问题。

处理预订和检索 5xx 错误

预订错误（5xx 状态）或超时不一定意味着预订本身是无效的，这个问题不能假定。该错误可能是在预订创建后发生的。因此，建议使用 affiliate_reference_id +电子邮件发出行程检索，以检查预订的状态。

在 90 秒内返回的任何错误并不代表预订的最终状态。通常情况下，大多数预订将在 13 到 30 秒内变成已确认预订，有些预订则可能需要长达 90 秒的时间才能处理完。

合作伙伴可以执行逻辑，在 90 秒内 3 次检查预订的状态。大多数响应将在最初的 30 秒内确认，之后合作伙伴即可确认响应，无需再等待整整 90 秒。如果没有得到最终响应，合作伙伴可以在 60 秒后再次检索，最后在 90 秒后验证最终响应。

使用检索 API 调用来双重确认预订结果（HTTP 200 或 HTTP 404 响应）。

检索响应返回保留/继续信息

在成功的预订后，行程检索响应偶尔会返回响应数据，看起来好像是保留/继续预订的响应数据。因此，除了预期的预订信息（客房、取消手续费等）外，响应将仅保留/继续情况所需的令牌。

响应示例：

{
  "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"
    }
  ]
}

原因是该预订虽然完全有效，但仍标有待处理标记。该标记通常会在几分钟内最终清除，因此，应重复发出行程检索申请，直到完成预订。

多级结构分解错误

当单一层级的错误无法解释所有细节时，API 响应可能会将一个错误分解成多个层级。迭代所有层级上的信息将有助于更好地澄清和排除错误。

响应示例：

{
    "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 响应代码

400 - 错误请求

在您的请求存在格式错误或包含不正确的值时返回。

代码 400 错误请求的错误表明申请预订的标头有问题。错误响应将包括预订请求标头中的实际错误数组字段，该字段是无效的。预订标头由一些数组和子数组组成，如客房和付款等。数组整体为正文。因此，body.email 将表示标头正文的电子邮件参数。

**注意：**预订标头客房数组的条目数必须与房态调用中请求的客房数目相同。

响应示例：

不支持的语言：

{
  "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"
        }
      ]
    }
  ]
}

缺少版本值：

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

无效的版本值：

{
  "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 - 未授权

找不到或无法分析 HTTP 授权标头时返回。对任何 Rapid API 服务的每个请求都必须包含您的 API 密钥串联的未加盐 SHA-512 哈希 + 共享秘钥 + UNIX 时间戳（以秒为单位）。有关完整的详细信息，请参考我们的签名授权页面。

401 未授权响应示例：

{
  "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 - 禁止

在您的 HTTP 授权标头有效，却无法访问请求的资源时返回。

403 禁止响应示例：

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

404 - 未找到

找不到请求的 API 资源时返回。请对照我们记录的示例来检查您的请求 URL。

地理 API 和内容 API 也使用 404 响应来表明找不到请求的地理/内容特定文件或资源。有关完整的示例，请参考其相应的文档页面。

行程检索后的代码 404 表示未找到预订。如果检索是由于预订错误而进行的，则表示预订并未创建。然而，合作伙伴需要确保行程检索 API 请求参数是有效的，所以要确保检索affiliate_reference_id、电子邮件和/或行程编号正确无误。此外，如果检索 API 调用的时间与预订调用的时间相差不到 90 秒，则请再次尝试检索，确保与预订调用的间隔时间达到 90 秒以上。

响应示例：

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

409 - 价格不匹配

许多住宿和连锁酒店采用动态定价，又称“基于时间的定价”。这意味着，定价会根据供需算法而变化。Expedia Group 每秒多次收到住宿的更新房价，这意味着房价变化频繁。

需要注意的是，这通常是住宿的选择，而不是 EPS 的选择。此外，由于在房价/房态方面有多级缓存，包括在合作伙伴层级，任何预订都可能会产生几层延迟。

价格不匹配 (PMM) 是一种预料之中的情况，可能由于一系列原因而发生，包括系统降级或系统没有反映住宿输入的最新价格。合作伙伴应监测这些活动的发生频率，如果房价突升或达到阈值，则应联系 EPS 支持中心。

如果多个住宿/客房同时出现了 PMM 的问题，则请检查是否存在潜在的 Rapid 降级。

在很长一段时间内，如果相同的房价/客房一直返回 PMM 问题，则可能是由于住宿的房价加载错误。请联系 EPS 技术支持部门进行检查。

要从 PMM 中恢复过来，请再次进行价格检查 API 调用，获得一个新的预订 URL 令牌。之后即可在预订调用中使用相同的 affiliate_reference_id。

响应示例：

{
  "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 - 售完或订满

在正在跟踪的 Rapid 链接已过期或者请求的客房已订完时返回。

许多连锁酒店和住宿都与 Expedia Group 建立了直接通信链接。同步通信是一种交互式交换，在 Expedia Group 和住宿/连锁酒店之间实时发生。

同步通信预订是指住宿或连锁酒店向 EPS 提供其客房库存（房态和房价），由 EPS 管理，随后根据该数据进行预订房态和价格检查调用。然后，在预订时，向住宿进行同步预订调用，以便预订客房。当所选客房的库存不足时，就会出现这个错误。如果发现库存不足，Rapid 将返回代码为 410 的错误消息。

这种情况可能是暂时的，重试后可能会发现可订空房。等待 90 秒，然后使用与预订一起发送的同一个 affiliate_reference_id，通过检索请求检查预订的状态。如果未找到预订，则用户可能不得不选择另一个住宿/客房/房价/日期组合。

住宿连接降级也可能会出现订满的错误消息，由于 Rapid 没有显示实际的房态，因此将显示订满的错误消息。

响应示例：

链接过期：

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

订满：

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

426 - 需要升级

请求未使用 TLS（取代 SSL）时返回。

响应示例：

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

429 - 速率限制错误

**注意：**如果您收到请求过多的错误，请至少等待 5 分钟，然后再尝试更正的请求。更频繁的重试会引起因缓存时间而产生的重复故障。

当请求计数超过速率限制时，将返回 429 状态代码。每个请求可能会受到两种不同的速率限制的制约：当集成以超过限制的速度发送请求时的速率限制，以及当 Expedia Group 服务器遇到负载超限时的速率限制。

合作伙伴发出 Expedia Group API 请求时，接收服务器会检查请求计数是否在限制范围内。如果请求计数在限制范围内，该请求会通过，并且客户端的计数会增加。如果客户端请求计数超过限制，则服务器会返回包含 HTTP 429（请求过多）状态代码的响应。

服务器可以选择性地包括 Rate-Limit-Day-Reset 和 Rate-Limit-Minute-Reset 标头。这表示在发送下一个请求之前您应等待的时间。它们是下一次发生滚动时的时间戳，单位是微秒（不是毫秒）。

例如，当转换为日期/时间时，数值“15489792000000”的结果是 Friday, February 1, 2019 12:00:00 AM（UTC）。

响应示例：

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 - 内部服务器错误

Rapid 的 API 或上游系统内存在错误时返回。如果给出了具体操作，请按照消息字段中的说明进行操作，否则，只需再次尝试使用相同的 affiliate_reference_id 发出请求。

当 Rapid 检测到问题，但不能更具体地说明确切问题是什么时，Rapid 会以 HTTP 500 做出响应。在使用 Rapid 的过程中，所有合作伙伴都会不时遇到一些代码为 500 的响应。

使用不支持的销售网站（如叙利亚）也可能会发生 HTTP 500 错误。

如果您在除创建预订或取消预订以外的 API 响应中收到错误，并且没有已知的降级，则请稍后重试您的请求。响应可能会包含一个 Retry-After 标头，指明再次尝试前的最短延迟时间（以秒为单位）。

如果您在创建预订时收到 API 响应中的错误：

• 等待 90 秒，然后使用与预订一起发送的同一个 affiliate_reference_id，通过检索请求检查预订的状态。
• 如果没有找到预订或继续收到 500 错误，请稍后再次尝试预订。

如果您在取消预订时收到 API 响应中的错误：

• 等待 90 秒，然后使用已知的 itinerary_id，通过行程检索请求检查预订的状态。
• 如果预订并未取消或继续收到 500 错误，请稍后再次尝试取消请求。

响应示例：

{
  "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

HTTP 503 错误通常是暂时性的，表示 Rapid 或下游服务目前无法处理请求。从暂时过载到与住宿的连接丢失，出现这个错误的可能原因有很多。

如果您在除创建预订或取消预订以外的 API 响应中收到错误，并且没有已知的降级，则请稍后重试您的请求。响应可能会包含一个 Retry-After 标头，指明再次尝试前的最短延迟时间（以秒为单位）。

如果您在创建预订时收到 API 响应中的错误：

• 经过一段较短的时间后，之前的价格检查响应中的预订链接将失效。如果您在首次尝试后收到 HTTP 503 错误，则该链接可能已失效。请获取新链接并再次尝试进行预订。
• 如果您在第二次尝试时收到 503，请等待 90 秒，然后使用与预订一起发送的同一个 affiliate_reference_id，通过检索请求检查预订的状态。
• 如果没有找到预订或继续收到 503 错误，请稍后再次尝试预订。

如果您在取消预订时收到 API 响应中的错误：

• 等待 90 秒，然后使用已知的 itinerary_id，通过行程检索请求检查预订的状态。
• 如果预订并未取消或继续收到 503 错误，请稍后再次尝试取消请求。

响应示例：

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

504 - 网关超时

HTTP 504 错误通常并非来自 Rapid，而是来自云或边缘基础设施，表示网络基础设施中的某个项目（如负载平衡器）在交易过程中发生故障。这通常是暂时性事件。

请注意，创建行程之前或之后都有可能发生超时，所以一定要检查，确认是否已创建行程。

HTTP 504（和 502）错误响应的格式为 HTML，而不是 Rapid JSON 类型/消息对象对。这也说明这些错误并非由 Rapid 产生。

响应示例：

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

房价错误响应的限值标准

为了建立其自有的限值，合作伙伴应衡量以下响应代码的每日房价：409、410、500、503 和 504。如果突破了限值，则应联系 EPS 支持中心。

EPS 并无任何固定限值，因为该限值实际上取决于合作伙伴所处的市场和销售对象以及其他因素。对市场的了解对于确定为什么会出现一些错误反应至关重要。指南预计每天或每周有高达 5-6% 的预订调用会出现代码为 50xx 的错误。

随着时间的推移，合作伙伴应该能够计算出其自己的限值。合作伙伴不能只是指望日常的突增。举例而言，即使设置了每天 5 个的限值，每个限值在 5 分钟内得到两个 500 错误也可能需要 EPS 支持中心核实原因。

日志

如果 EPS 要求提供请求/响应日志，请尝试提供以下内容：

• API 响应标头中的 Transaction-Id 值。这对深入调查至关重要。
• API 请求和响应日志。请求日志应包括所使用的完整端点 URL。响应日志应该包括返回的 HTTP 代码、完整的响应数据和返回的任何标头。
• 参数为 point_of_sale 的房态 API 请求以及房态响应。这将使 EPS 支持中心能够识别正在使用的 Rapid 帐户和资料。
• 每个预订请求的预订 API 请求标头和授权标头（含 APIKey、签名和时间戳）。
• 请求日志中的预订请求 URL 和令牌。
• 无论预订调用是成功还是失败，行程检索均在预订 API 调用后发出。

请包括完整的 JSON 请求和响应。JSON 字符串必须使用双引号，因此无需在双引号字符前加上反斜杠转义字符。

需要双引号成为字符串的一部分时，才会在双引号前使用反斜杠转义字符。

响应示例：

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

请勿以 PDF 格式呈现日志。EPS 支持中心和开发人员有时会将日志数据复制/粘贴到内部工具中，而 PDF 格式会为数据添加不必要的换行字符。

附录

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" }}}