常見錯誤回應
我們的 API 服務會分享下列常見錯誤碼、訊息與回應格式。
Rapid 錯誤處理建議
錯誤處理邏輯
- 平台與合作夥伴應確保已建立錯誤處理邏輯，以處理購物與預訂 API 的錯誤。
- 除非下方的註釋有指明，否則每個預訂要求都要使用唯一的
affiliate_reference_id。 - 您應持續檢視並更新錯誤處理邏輯，特別是針對預訂請求。
- 所有 Rapid API 的回應皆對應一個 HTTP 狀態碼，請參閱下方回應 HTTP 狀態碼清單。
連線逾時或通訊逾時
建議為航班 API 預訂請求設定 120 秒的 API 連線超時值；至於住宿及其他 API，則建議設定為 90 秒。然而，您可能決定為購物庫存查詢使用較短的連線超時設定。
若未在 120 秒內收到回應，Rapid API 將發出 5xx 錯誤，因為 Rapid API's 的連線超時設定為 120 秒。
在某些情況下，Rapid API 不支援HTTP 預期狀態碼：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 秒內實施邏輯檢查預訂狀態三次。多數回應將在最初 30 秒內確認，屆時您無需等待滿 90 秒即可確認該回應。若尚未收到最終回覆，您可在 30 分鐘內重新嘗試檢索，之後請聯繫 Rapid API 客服中心人員以獲取進一步支援。
使用檢索 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,，例如房間和付款資訊。整個陣列都是主體。因此，body.email 將表示該標頭主體的電子郵件參數。
註： 針對住宿 API，預訂標頭中的 rooms 陣列必須與可用性查詢中請求的房間數量完全一致。
要求參數過大時，系統通常會在「旅宿內容」和「獲取供應情況 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 時間戳 (以秒為單位) 的串接結果。若要了解完整詳細資料，請參閱我們的簽章授權頁面。
範例住宿 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
}
]
}對於快速飛行 API 呼叫，您必須在請求標頭中包含有效的EGToken 主要 JSON 網路憑證 (JWT)。
Authorization: EGToken principal-JWT={encodedJwt}主要 JWT 透過 OAuth 2.0 客戶端憑證與代幣交換取得；詳情請參閱OAuth 2.0 驗證指南 及快速航班預訂 API 使用說明。
403 - 禁止
若 HTTP 授權標頭有效，但您未獲允許存取所要求的資源，便會傳回此訊息。
403 禁止回應範例：
{
"type": "request_unauthorized",
"message": "Your request could not be authorized."
}404 - 找不到
若找不到所要求的 API 資源，便會傳回此訊息。將您的要求 URL 與文中記載的範例對照。
住宿服務地理 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 格式會為資料添加不必要的換行符號。
附錄
尚未迅速解決的預訂範例
確認預訂範例
預訂失敗範例
