共通エラー応答

当社の API サービスは、次に示すエラーコード、エラーメッセージ、エラー応答のフォーマットを共有しています。サービスに固有のエラー応答については、個々の説明ページを参照してください。

Rapid でのエラー処理に関する推奨事項

エラー処理ロジック

• プラットフォームとパートナーは、Rapid のエラーを処理するために検索 & 予約エラー処理ロジックを適用する必要があります。
• 以下の注意事項で指定されていない限り、すべての予約リクエストで必ず一意の affiliate_reference_id を使用してください。
• パートナーは、特に予約リクエストに関するエラー処理ロジックを繰り返し見直し、更新する必要があります。
• すべての Rapid 応答に対応する HTTP コードがあります。応答 HTTP コード一覧は以下を参照してください。

接続タイムアウトまたは通信タイムアウト

予約リクエストには 90 秒の API 接続タイムアウト設定が推奨されています。他の API については、特に推奨されている設定はありませんが、タイムアウトが金銭的損失をもたらすわけではないため、同様のタイムアウト設定を適用してください。ただし、パートナーによっては、ショップ空室状況呼び出しにこれより短い接続タイムアウトを使用しても構いません。

120 秒以内に応答がなければ、それ以降に応答が来ることはありません。これは、EPS Rapid には独自のタイムアウト設定があり、120 秒が Rapid の最長タイムアウトとなるためです。120 秒が経過すると、Rapid から 5xx エラーが発行されます。

一部のケースでは、Rapid が HTTP Expect: 100-Continue のプロセスに対応していません。特に cURL、C#/.NET、デフォルトでプロセスに従うその他一部のコーディング言語において、プロセスでサーバーに接続しようとすると、接続の問題が発生する可能性があります。

注 : HTTP 504 のゲートウェイタイムアウトが発生しても、Rapidでタイムアウトが発生したというわけではありません。このような場合は、インフラストラクチャサービスに障害が発生しているか、Rapid が別のダウンストリームサービスへのゲートウェイとして動作しており、そのサービスのタイムアウト制限を設定します。このタイムアウトがトリガーとなり、EPSは 504 として報告する必要があります。予約の呼び出しで 504 が発生した場合、下流の問題は予約が作成される前 (例 : ホテルの通信、支払いサーバー) または予約が作成された後（例 : EPS ファイナンスマネジメント) である可能性があるため、予約が作成されたかどうか、または Itinerary Retrieve (affiliate_reference_id + メール) が使用されていないかどうかを確認してください。また、インターネット接続が安定していることを確認してください。Traceroute コマンドで接続の問題を特定できる場合もあります。

予約と取得 5xx エラーの処理

予約エラー (5xx ステータス) やタイムアウトが発生しても、予約自体が無効であるとは限らないため、思い込みに注意しましょう。予約が作成された後にエラーが発生した可能性があります。そのため、affiliate_reference_id + メールで Itinerary Retrieve を実行して予約のステータスを確認することが推奨されています。

90秒以内に返されたエラーは、予約の最終的なステータスを示すものではありません。通常、ほとんどの予約は 13 ～ 30 秒以内に予約確定になりますが、中には予約確定に 90 秒かかるものもあります。

パートナーは予約のステータスを 90 秒間に 3 回確認するロジックを実装できます。ほとんどの応答は最初の 30 秒以内に確認され、パートナーは 90 秒経過するまで待たずに応答を確認できます。最終的な応答を受信していない場合、パートナーは 60 秒後に再度取得し、最終的に 90 秒後に最終的な応答を検証できます。

Retrieve API 呼び出しを使用して、予約結果 (HTTP 200 応答か HTTP 404 応答) をダブルチェックします。

Retrieve の応答が Hold\Resume 情報を返す

予約に成功した後、Itinerary Retrieve の応答が、Hold/Resume 予約に対するもののように見える応答データを返すことがあります。そのため、期待される予約情報 (客室、キャンセル料など) ではなく、Hold/Resume の状況に必要なトークンだけがレスポンスに含まれることになります。

レスポンスの例 :

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

その理由は、予約が完全に有効であるにもかかわらず、まだ保留のフラグが立っているためです。通常、この現象は数分以内に解消されるため、予約が完了するまで Itinerary Retrieve リクエストを繰り返してください。

複数のレベルに分類されるエラー

1 つのレベルのエラーでは詳細をすべて説明できない場合、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 - Bad Request

リクエストの形式が不適切であったり、不正な値が含まれていたりする場合に返されます。

コード 400 Bad Request のエラーが発生した場合は、リクエスト予約ヘッダーに問題があります。予約リクエストヘッダーの中で無効となった実際のエラー配列フィールドがエラー応答には含まれます。予約ヘッダーは、客室や支払いなど、いくつかの配列とサブ配列で構成されています。配列全体が本文です。つまり、body.email はヘッダー本文のメールパラメーターを示します。

注 : Book ヘッダー客室配列には、Availability 呼び出しでリクエストされた客室と同じ数のエントリが必要です。

「Tomcat Exception Report」とラベル付けされた 400 Bad Request エラーは、通常は Property Content API と Get Availability API でリクエストパラメーターが大きすぎる場合に返されます。このエラーを回避するには、プロパティの数を減らすか、リクエストから不要なパラメーターを削除します。

応答の例 :

ご希望の言語は対応していません :

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

HTTP 認証ヘッダーを検出できないか解析できない場合に返されます。Rapid のすべての API サービスへのリクエストには、API キー + 共有秘密 + UNIX タイムスタンプ (秒) を連結したソルトのない SHA-512 ハッシュが含まれる必要があります。詳細については、シグネチャー認証のページを参照してください。

401 - Unauthorized 応答の例 :

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

HTTP 認証ヘッダーは有効ですが、リクエストされたリソースへのアクセス許可がない場合に返されます。

403 禁止応答の例

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

404 - Not Found

リクエストされた API のリソースが検出できない場合に返されます。EAN の記載例で、リクエストした URL を確認してください。

Geography API と Content API も、リクエストされた地理やコンテンツ向けのファイルやリソースが検出できない場合に、404 応答を使用します。詳しい例については、それぞれの文書ページを参照してください。

Itinerary Retrieve の後のコード 404 は、予約が見つからなかったことを示します。予約エラーのために取得が行われた場合、予約が作成されなかったと表示されます。ただし、パートナーは、Itinerary Retrieve API のリクエストパラメーターが有効であったことを確認する必要があるため、Retrieve affiliate_reference_id、メール、および / または旅程番号が正しいことを確認してください。また、Retrieve API の呼び出しが Booking の呼び出しから 90 秒未満で行われた場合は、Booking の呼び出しから 90 秒以上経っていることを確認して、再度取得してみてください。

応答の例 :

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

409 - Price mismatch

多くの宿泊施設とホテルチェーンでは、ダイナミックプライシング (「変動料金制」とも呼ばれる) を採用しています。そのため、需要と供給のアルゴリズムに基づいて価格が変動します。Expedia Group では 1 秒間に何度も宿泊施設から最新の料金を受信しているため、料金は頻繁に変わります。

通常、価格を決定するのは EPS ではなく宿泊施設である点に注意してください。さらに、パートナーレベルを含む複数のレベルで料金 / 在庫のキャッシュが存在するため、予約には何層もの遅延要因が存在する可能性があります。

価格の不一致 (PMM) は想定の範囲内であり、システムのパフォーマンス低下や、宿泊施設が入力した最新価格がシステムに反映されていないなど、さまざまな理由で発生する可能性があります。パートナーはこれらのイベントの頻度をモニタリングし、料金が突然上昇したり、閾値に達したりした場合には EPS サポートに連絡する必要があります。

複数の宿泊施設 / 客室で PMM が同時発生した場合は、Rapid のパフォーマンス低下が発生していないか確認してください。

長期間にわたって同じ料金 / 客室で PMM が返された場合は、宿泊施設が料金を誤って読み込んでいる可能性が考えられます。この場合は EPS テクニカルサポートに問い合わせて確認してください。

PMM から復旧するには、再度 Price Check API を呼び出し、新しい Booking 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 - Gone or sold out

フォローしている Rapid リンクが期限切れであるか、要求された客室が利用できなくなっている場合に返されます。

多くのホテルチェーンと宿泊施設が Expedia Group との直接通信回線を持っています。同期通信は、Expedia Group と宿泊施設 / チェーン間でリアルタイムに行われるインタラクティブなやりとりです。

同期通信予約とは、宿泊施設やチェーンが EPS に客室の在庫 (空室状況と価格) を提供し、EPS がそれを管理し、そのデータに対してその後の Shop Availability 呼び出しと Price Check 呼び出しが行われることです。予約時には、同期予約呼び出しが宿泊施設に対して実行され、客室が予約されます。選択した客室の在庫が不足している場合にこのエラーが発生します。在庫が不足していることが判明した場合、Rapid からコード 410 エラーメッセージが返されます。

これは一時的なものである可能性があり、再試行で空室が見つかることもあります。90 秒待機してから、予約と一緒に送信された同じ affiliate_reference_id を使用して、Retrieve リクエストで予約のステータスを確認します。予約が見つからない場合、ユーザーは別の宿泊施設 / 客室 / 料金 / 日付の組み合わせを選択する必要がある場合があります。

宿泊施設との接続品質が低下しているために 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 - Upgrade required

リクエストで TLS (SSL の後継) が使用されていない場合に返されます。

応答の例 :

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

429 - Rate limit error

注意 : リクエスト数が多すぎるというエラーが表示された場合は、5 分以上待ってから修正したリクエストを試してください。再試行回数が多くなると、キャッシュのタイミングにより失敗を繰り返すことになります。

リクエスト数がレート制限を超えた場合は 429 ステータスコードが返されます。各リクエストは 2 つの異なるレート制限に従います。統合が制限値を超える割合でリクエストを送信している場合のレート制限と、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 - Internal server error

Rapid の API またはアップストリーム システム内のエラーを返します。特定の操作が指定されている場合は、メッセージフィールドの指示に従ってください。それ以外の場合は、同じ affiliate_reference_id でリクエストをやり直してください。

Rapid で問題が検出された場合は HTTP 500 応答が返されますが、正確な問題をより具体的に説明することはできません。すべてのパートナーは、Rapid の使用において、コード 500 応答があることを予期しておく必要がある場合があります。

シリアなど、サポートされていない POS が利用されている場合にも HTTP 500 エラーが発生することがあります。

予約の作成または予約のキャンセル以外の API 応答でエラーを受け取り、既知のパフォーマンス低下がない場合は、後でリクエストを再試行してください。再試行する前の最小遅延 (秒) を示す Retry-After ヘッダーが応答に含まれる場合があります。

予約作成時に API 応答でエラーが表示された場合 :

• 90 秒待機してから、予約と一緒に送信された同じ affiliate_reference_id を使用して、Retrieve リクエストで予約のステータスを確認します。
• 予約が見つからなかったり、500 エラーが続く場合は、時間をおいて予約を再試行してください。

予約のキャンセル時に API 応答でエラーが返された場合 :

• 90 秒待機してから、既知の itinerary_id を使用して、Retrieve リクエストで予約のステータスを確認します。
• 予約がキャンセルされていなかったり、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 エラーを受信した場合は、リンクが失効している可能性があります。新たなリンクを取得して再度予約してください。
• 2 回目の試行で 503 になった場合は、90 秒待機してから、予約と一緒に送信された同じ affiliate_reference_id を使用して、Retrieve リクエストで予約のステータスを確認します。
• 予約が見つからなかったり、503 エラーが続く場合は、時間をおいて予約を再試行してください。

予約のキャンセル時に API 応答でエラーが返された場合 :

• 90 秒待機してから、既知の itinerary_id を使用して、Retrieve リクエストで予約のステータスを確認します。
• 予約がキャンセルされていなかったり、503 エラーが続く場合は、時間をおいてキャンセルリクエストを再試行してください。

応答の例 :

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

504 - Gateway time out

通常、HTTP 504 エラーは Rapid からではなく、クラウドまたはエッジインフラストラクチャから返され、トランザクション中にネットワークインフラストラクチャ内のアイテム (ロードバランサーなど) に障害が発生したことを示します。一般的には一時的な現象です。

なお、タイムアウトは旅程作成の前後に発生することがあるため、旅程が作成されたかどうかを必ず確認してください。

HTTP 504 (および 502) エラー応答は、Rapid JSON タイプ / メッセージオブジェクトのペアではなく、HTML 形式です。このことも、これらのエラーが 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 ではしきい値を設定していません。エラー応答が発生する理由を判断するには、マーケットプレイスに関する知識が不可欠です。ガイダンスでは、毎日または週に 1 度のペースで予約呼び出しの最大 5 ～ 6％ がコード 50xx エラーで失敗することを想定しています。

時間が経てば、パートナーが自身でしきい値を計算できるようになるはずです。1 日単位の急激な増加だけに注目しないでください。1 日あたり 5 というしきい値が設定されていても、5 分以内に 2 つの 500 エラーが発生した場合などは、EPS サポートに確認する理由となることがあります。

ログ

EPS からリクエスト / 応答ログの提出を求められた場合は、以下を提供してください。

• API 応答ヘッダーの Transaction-Id の値。これは詳しい調査に欠かせないものです。
• API のリクエストログと応答ログの両方。リクエストログには、使用された完全なエンドポイント URL を含める必要があります。返された HTTP コード、完全な応答データ、返されたヘッダーを応答ログに含める必要があります。
• point_of_sale パラメーターを指定した Availability API リクエスト、および Availability の応答。これらがあることで、使用されている Rapid アカウントとプロファイルを EPS サポートが特定できるようになります。
• 各予約リクエストの Booking API リクエストヘッダーと認可ヘッダー (APIKey、署名、タイムスタンプを含む)。
• リクエストログの Booking リクエスト URL とトークン。
• Booking API 呼び出しの後に発行される Itinerary Retrieve (Booking の呼び出しが成功したか失敗したかは無関係)。

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