常見錯誤回應

我們的 API 服務會分享下列常見錯誤碼、訊息與回應格式。若要檢視每項服務的獨有錯誤訊息，請參閱各項文件頁面。

Rapid 錯誤處理建議

錯誤處理邏輯

• 平台與合作夥伴應確保制訂出選購和預訂的錯誤處理邏輯，以便處理 Rapid 錯誤。
• 除非下方的註釋有指明，否則每個預訂要求都要使用唯一的 affiliate_reference_id。
• 合作夥伴應不斷檢查並更新他們的錯誤處理邏輯，特別是針對預訂要求。
• 所有的 Rapid 回應都有一個相應的 HTTP 代碼，請見下方的回應 HTTP 代碼清單。

連線逾時或通訊逾時

建議將「預訂」要求的 API 連線逾時設定為 90 秒。雖然對其他 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 秒內回傳的任何錯誤，並不代表預訂的最終狀態。儘管有些預訂可能需要長達 90 秒的時間來解決，但在一般情況下，多數預訂仍會在 13 - 30 秒內解決並轉換成已確認的預訂。

合作夥伴可以實作邏輯，在 90 秒內檢查預訂狀態 3 次。多數回應會在前 30 秒內確認，然後合作夥伴可以確認回應，而無需等待整整 90 秒。如果尚未收到最終回應，合作夥伴可以在 60 秒後再次擷取，然後在 90 秒後做最終擷取以驗證最終回應。

使用「擷取 API」呼叫再次確認預訂結果 (HTTP 200 或 HTTP 404 回應)。

擷取回應回傳保留/恢復資訊

有時，在預訂成功後，行程擷取回應會回傳回應資料，而且會看來像是保留/恢復預訂。因此，除了預期的預訂資訊 (客房、取消費用等) 外，該回應將僅有保留/恢復情況下所需的 Token。

回應範例：

{
  "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 將表示該標頭主體的電子郵件參數。

**請注意：**該預訂標頭客房陣列的項目數，必須與供應情況呼叫中要求的客房數相同。

要求參數過大時，系統通常會在「旅宿內容」和「獲取供應情況 API」上回傳標記為「Tomcat Exception Report」的 400 錯誤要求的錯誤。若要避免此錯誤，請減少旅宿數量或刪除要求中不必要的參數。

回應範例：

不支援的語言：

{
  "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 金鑰、共用密碼與 UNIX 時間戳記 (單位為秒) 的** Unsalted SHA-512 雜湊**。若要了解完整詳細資料，請參閱我們的簽章授權頁面。

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 秒，則從「預訂」呼叫，然後再次嘗試擷取，確保 API 呼叫是在「預訂」呼叫超過 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」Token。然後您就可以在預訂呼叫中，使用相同的 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 標頭。此標頭表示傳送下個要求前所需的等候時間。以及下一次 Tumble 函數將出現的時間戳記，單位是微秒 (不是毫秒)。

例如，轉換為日期/時間時，該值「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 - 無法提供服務

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 和 Token。
• 無論「預訂」呼叫是成功還是失敗，都請呼叫預訂 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" }}}