常見錯誤回應
Rapid API 各業務部門共用相同的錯誤代碼、訊息及回應格式
這些錯誤適用於 Rapid 的所有業務線，包括：
- Rapid Lodging API
- Rapid Car API
- Rapid Flight API
- Rapid Activities API
各業務部門之間的任何差異均已註明。
Rapid API 錯誤處理
為避免發生問題，我們建議您的錯誤處理邏輯應包含以下要點：
- 請確保已建立錯誤處理邏輯，以處理購物與預訂 API 的錯誤。
- 除非下方備註另有說明，否則請務必為每筆預訂請求使用唯一的
affiliate_reference_id。 - 請定期檢視並更新您的錯誤處理邏輯，特別是針對預訂請求的部分。
- 所有 Rapid API 的回應都對應一個的 HTTP 回應代碼。
連線逾時或通訊逾時
針對 Flight API 預訂請求，建議將 API 連線超時設定為 120 秒；至於住宿及其他 API，則建議設定為 90 秒。不過，您也可以選擇為「購物庫存查詢」請求設定較短的連線超時時間。
如果您在 120 秒內未收到回應，Rapid API 將會回傳 5xx 錯誤，因為 Rapid API's 的連線超時設定為 120 秒。
在某些情況下，Rapid API 不支援HTTP Expect: 100-Continue 的處理流程。當您嘗試透過此流程連線至伺服器時，可能會遇到連線問題，特別是在 cURL、C#/.NET 以及其他預設採用此流程的程式語言中。
**請注意：**HTTP 504 閘道逾時，並不表示 Rapid 已逾時。在這些情況下，要麼是基礎架構服務發生故障，要麼是 Rapid 作為通往另一個下游服務的閘道，並為該服務設定了超時限制。該下游超時將觸發 504 錯誤。若預訂呼叫發生 504 錯誤，請確認該預訂是否是透過「行程擷取」（affiliate_reference_id+ 電子郵件）功能建立的，因為下游問題可能發生在預訂建立之前 (飯店通訊、支付伺服器) 或之後 (Expedia Group 財務管理)。此外，請確認網路連線是否穩定。Traceroute 命令可能有助於找出任何連線問題。
處理預訂和擷取 5xx 錯誤
預訂錯誤 (5xx 狀態碼) 或超時，並不一定代表預訂本身無效。錯誤可能會在預訂建立後發生。我們建議您透過affiliate_reference_id 加上電子郵件發送「行程查詢」請求，以確認預訂狀態。
90 秒內回傳的任何錯誤，並不代表預訂的最終狀態。通常，大多數預訂會在 13 至 30 秒內確認，但部分預訂可能需要長達 5 分鐘才能完成。
您可以在 90 秒內最多檢查預訂狀態 3 次。大多數回應會在最初的 30 秒內確認，屆時您即可確認該回應，無需等待完整的 90 秒。若未收到最終回覆，您可在 30 分鐘內重新嘗試檢索，之後再聯絡 Rapid API 客服中心人員以獲取進一步協助。
使用 Retrieve API 呼叫來擷取預訂結果 (double-confirm)(回應狀態為 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"
}
]
}多層次結構的錯誤分解
當「single-level」錯誤無法說明所有必要細節時，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「請求錯誤」表示 Request Booking 標頭出現問題。錯誤回應將包含預訂請求標頭中實際無效的錯誤陣列欄位。標頭包含多個陣列以及 sub-arrays,，例如 rooms 和 payments。 整個陣列都是主體。因此，body.email 將表示該標頭主體的電子郵件參數。
注意： 對於 Lodging API，Booking 請求頭中的 rooms 陣列所含項目數量，必須與在 Availability 呼叫中請求的房間數量相同。
要求參數過大時，系統通常會在「旅宿內容」和「獲取供應情況 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 Lodging API 的請求都必須包含以下無鹽雜湊值：SHA-512，該值由您的 API 金鑰、共享密鑰以及以秒為單位的 UNIX 時間戳串接後計算得出。若要了解完整詳細資料，請參閱我們的簽章授權頁面。
Lodging API 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
}
]
}對於 Rapid Flight API 呼叫，您必須在請求標頭中包含有效的EGToken 主體 JSON 網路憑證 (JWT)。
Authorization: EGToken principal-JWT={encodedJwt}主要 JWT 是透過 OAuth 2.0 客戶端憑證與代幣交換機制取得；詳細資訊請參閱的 OAuth 2.0 驗證指南 以及的 Rapid Flight Booking API 使用指南。
403 - 禁止
若 HTTP 授權標頭有效，但您未獲允許存取所要求的資源，便會傳回此訊息。
403 禁止回應範例：
{
"type": "request_unauthorized",
"message": "Your request could not be authorized."
}404 - 找不到
若找不到所要求的 API 資源，便會傳回此訊息。將您的要求 URL 與文中記載的範例對照。
Lodging地理位置 API以及內容 API也會使用 404 回應，以表示無法找到所請求的地理位置或 content-specific 檔案或資源。如需完整範例，請參閱各自的文件頁面。
行程擷取後的代碼 404，表示無法找到預訂。如果擷取作業是因預訂錯誤而開始，系統便會顯示該預訂沒有建立。不過，您必須確保「行程擷取 API」的請求參數有效，因此請確認「擷取affiliate_reference_id」、電子郵件地址及／或行程編號是否正確。此外，若「檢索」API 呼叫是在「預訂」呼叫後 90 秒內發出的，我們建議您重新嘗試檢索。
回應範例：
{
"type": "resource.not_found",
"message": "The requested resource could not be found."
}409 - 房價不符
許多供應商採用動態定價，亦即所謂的「time-based 定價」。這表示，價格會因供需演算法而異。Expedia Group 每秒會接收數次更新的費率，這意味著費率變動頻繁。
必須注意的是，這通常是由供應商決定，而非 Expedia Group. 此外，由於價格和空房狀況會經過多層級的快取處理，因此任何預訂流程中都可能存在多層延遲。
價格不匹配 (PMM) 是一種預期中的情況，可能因多種原因而發生，包括系統效能 下降，或系統未能反映最新價格。您應監控此類事件的發生頻率，若發生率突然上升或達到閾值，請聯絡支援團隊。
如果多個結果同時發生 PMM，您應檢查是否可能出現快速劣化。
如果 PMM 在一段長時間內始終顯示相同的結果，那麼這很可能是因為供應商載入的費率有誤所致。您可以聯絡技術支援部門進行確認。
若要從 PMM 狀態恢復，請再次呼叫「價格查詢」（住宿 API）或「航班詳情」(航班 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 API 連結已過期，或所請求的庫存已無庫存，則返回此狀態。
許多供應商與 Expedia Group 之間設有直接且同步的通訊連結，並以即時方式運作。
所謂的同步通訊預訂，是指針對我們所管理的供應商資料，發出「購物庫存與價格查詢」（住宿 API）或「航班詳情」（航班 API）的請求。當預訂選項的庫存不足時，會發生此錯誤。
這可能是暫時性的狀況，稍後再試可能就會發現庫存已恢復。請等待 90 秒，然後使用與預訂一起傳送的相同 affiliate_reference_id 擷取要求來檢查預訂狀態。如果找不到預訂記錄，旅客可能需要選擇其他方案。
若與供應商的連線品質下降，也可能出現「已售罄」的錯誤訊息。在這種情況下，我們無法得知實際的可用性。
回應範例：
連結已過期：
{
"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 - 速率限制錯誤
當請求次數超過速率限制時，系統會回傳 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)。
**請注意：**如果您收到請求過多的錯誤，請等待至少 5 分鐘後再嘗試更改請求。頻繁重試將導致因快取時間而產生的重複失敗。
回應範例：
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-6d74226e7f00500 - 內部伺服器錯誤
回傳發生於 Rapid API 或上游系統中的錯誤。如果特定動作出現，請按照訊息欄位中的說明進行操作，或請再次嘗試相同的 affiliate_reference_id 要求即可。
Rapid API 當系統偵測到問題時，會回傳 HTTP 500 狀態碼，但無法具體說明問題的詳細原因。所有合作夥伴在使用 Rapid API 時，應預期偶爾會收到 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, 或其下游服務目前無法處理此請求。這可能有許多原因，從暫時性的負載過載到與供應商的連線中斷皆有可能。
如果您在「建立預訂」或「取消預訂」以外的 API 回應中收到此錯誤，且未發現系統效能下降的情況，請稍後再重新嘗試您的請求。回應可能會包含 Retry-After 標頭，以表示重試前的最短延遲時間 (單位為秒)。
如果您在建立預訂時收到 API 回應中的錯誤：
- 您先前透過「價格查詢」（住宿 API）或「航班詳情」（航班 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 API，而是來自雲端或邊緣基礎架構，這表示網路基礎架構中的某個元件 (例如負載平衡器) 在交易過程中發生故障。這通常只是一時的情況。
注意： 超時情況可能發生在行程建立之前或之後，因此請務必確認行程是否已建立。
HTTP 504 (以及 502) 錯誤回應採用 HTML 格式，而非 Rapid API's 中的 JSON 類型/訊息對。這進一步表明，這些錯誤並非由 Rapid API.
回應範例：
<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。若超過閾值，請聯絡 Rapid API 技術支援。
Expedia Group 沒有任何固定的閾值，因為這些數值會因貴組織所處的市場及其他因素而有所不同。了解市場狀況對於釐清某些錯誤回應發生的原因至關重要。我們的建議是，預期在每日或每週期間內，約有 5% 至 6% 的預訂來電會因 50x 錯誤代碼而失敗。
隨著時間推移，您應該能夠自行計算出這些閾值。不要只關注單日突發的增加——即使設定的閾值是每天 5 次，但例如在 5 分鐘內接連出現兩次 500 錯誤，就可能需要聯繫 Rapid API 技術支援進行查核。
記錄
若 Rapid API 技術支援人員要求提供請求/回應日誌，請盡量提供以下內容：
- API 回應標頭中的
Transaction-Id值。本數值對深入調查至關重要。 - API 要求和回應記錄都有。要求記錄應加入所使用的完整端點 URL。回應記錄應加入回傳的 HTTP 代碼、完整的回應資料，以及任何回傳的標頭。
- 含
point_of_sale參數的「供應情況 API」要求以及「供應情況」回應。這將有助於技術支援人員識別您所使用的 Rapid API 帳戶及個人檔案。 - 每次預訂請求的預訂 API 請求標頭與授權標頭 (包含 API 金鑰、簽名及時間戳記)。
- 要求記錄中的「預訂」要求 URL 和 Token。
- 無論「預訂」呼叫是成功還是失敗，都請呼叫預訂 API 後發出的「行程擷取」。
請加入完整的 JSON 要求和回應。JSON 字串必須採用 double-quoted, 格式，因此無需在 double-quote 字元前加上反斜線轉義字元。
| 優良的 JSON 代碼 | 不良的 JSON 代碼 |
|---|---|
json "id": "208646250", "status": "available", | json\"id\": \"208646250\", \"status\": \"available\", |
僅在需要將雙引號作為字串的一部分時，才應在雙引號前使用反斜線轉義字元。
回應範例：
"spokenwords": "He said "hello world""注意： 請勿將日誌轉為 PDF 格式。Expedia Group 技術支援人員有時會將日誌資料複製貼上至內部工具，而 PDF 格式會為資料增添不必要的換行字元。
附錄
尚未迅速解決的預訂範例
已確認預訂範例
預訂失敗範例
