일반적인 오류 응답
API 서비스는 다음과 같은 일반적인 오류 코드와 메시지, 응답 형식을 공유합니다.
Rapid 오류 처리 권장 사항
오류 처리 논리
- 플랫폼과 파트너는 쇼핑 및 예약 API 오류를 처리할 수 있는 오류 처리 로직이 마련되어 있는지 확인해야 합니다.
- 아래 참고 사항에 명시되지 않은 한 모든 예약 요청에 대해 항상 고유한
affiliate_reference_id를 사용합니다. - 특히 예약 요청에 대한 오류 처리 로직을 지속적으로 검토하고 업데이트해야 합니다.
- 모든 Rapid API 응답에는 해당 HTTP 코드가 있으며, 응답 HTTP 코드 목록은 아래를 참조하세요.
연결 시간 초과 또는 통신 시간 초과
항공편 API 예약 요청의 경우 120초의 API 연결 시간 제한 설정을 권장하며, 숙박 및 기타 API의 경우 90초를 권장합니다. 그러나 쇼핑 가용성 호출에는 더 짧은 연결 시간 초과를 사용할 수 있습니다.
120초 내에 응답을 받지 못하면 Rapid API's 자체 연결 시간 제한이 120초로 설정되어 있으므로 Rapid API 에서 5xx 오류가 발생합니다.
경우에 따라 Rapid API 은 HTTP 기대: 100-계속 프로세스를 지원하지 않습니다. 프로세스를 통해 서버를 연결하려고 할 때 연결 문제가 발생할 수 있으며, 특히 기본적으로 프로세스를 따르는 cURL, C#/.NET 및 일부 다른 코딩 언어에서 연결 문제가 발생할 수 있습니다.
참고: HTTP 504 게이트웨이 시간 초과가 Rapid가 시간 초과되었음을 의미하지는 않습니다. 이러한 경우 인프라 서비스에 장애가 발생했거나 Rapid가 다른 다운스트림 서비스의 게이트웨이 역할을 하고 있으며 해당 서비스에 대한 시간 제한을 설정하고 있습니다. 해당 다운스트림 시간 초과가 504로 트리거됩니다. 예약 전화에 504가 발생한 경우, 다운스트림 문제가 예약 생성 전(호텔 커뮤니케이션, 결제 서버) 또는 후(Expedia Group 재무 관리)에 발생했을 수 있으므로 일정 검색(affiliate_reference_id+ 이메일)을 사용하여 예약이 생성되었는지 확인해 주세요. 또한 인터넷 연결이 안정적인지 확인하세요. Traceroute 명령은 연결 문제를 식별하는 데 도움이 될 수 있습니다.
예약 처리 및 5xx 오류 검색
예약 오류(5xx 상태) 또는 시간 초과가 반드시 예약 자체가 무효임을 의미하지는 않습니다. 예약이 생성된 후 오류가 발생했을 수 있습니다. 예약 상태를 확인하려면 affiliate_reference_id+ 이메일 주소로 일정 Retrieve를 발행하는 것이 좋습니다.
90초 이내에 반환된 오류는 예약의 최종 상태를 나타내지 않습니다. 일반적으로 대부분의 예약은 13~30초 이내에 예약 확정으로 처리되지만, 일부 예약은 최대 5분이 소요될 수 있습니다.
90초 이내에 예약 상태를 3번 확인하는 로직을 구현할 수 있습니다. 대부분의 응답은 처음 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 - Bad Request
요청이 잘못되었거나 부적절한 값을 포함한 경우 반환됩니다.
코드 400 잘못된 요청 오류는 예약 요청 헤더에 문제가 있음을 나타냅니다. 오류 응답에는 예약 요청 헤더에 실제 유효하지 않은 오류 배열 필드가 포함됩니다. 헤더는 객실 및 결제와 같은 여러 배열과 sub-arrays, 로 구성됩니다. 전체 배열이 본문입니다. 따라서 body.email은 헤더 본문의 이메일 매개변수를 나타냅니다.
참고: 숙박 API의 경우 예약 헤더 객실 배열에는 예약 가능 여부 호출에서 요청된 객실과 동일한 수의 항목이 있어야 합니다.
요청 매개 변수가 지나치게 크면 "Tomcat Exception Report"라는 레이블이 지정된 400 잘못된 요청 오류가 반환되며, 이 오류는 대부분 숙박 시설 콘텐츠 및 예약 가능 객실 가져오기 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 인증 헤더가 누락되었거나 파싱할 수 없는 경우 반환합니다. 빠른 숙소 API에 대한 각 요청에는 API 키 + 공유 비밀번호 + UNIX 타임스탬프(초 단위)를 연결한 무염 SHA-512 해시 가 포함되어야 합니다. 자세한 정보는 서명 인증 페이지를 참조해 주세요.
숙박 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 - Forbidden
HTTP 인증 헤더가 유효하지만, 요청한 리소스에 액세스하도록 허용되지 않은 경우 반환됩니다.
403 Forbidden 응답 예:
{
"type": "request_unauthorized",
"message": "Your request could not be authorized."
}404 - Not found
요청한 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 - Price mismatch
많은 공급업체가 동적 가격 책정 또는 "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 - Gone or sold out
팔로우 중인 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 - Upgrade required
요청이 보안 소켓 계층(SSL)을 대체하는 암호화 프로토콜인 TLS(전송 계층 보안)를 사용하지 않은 경우 반환합니다.
응답 예:
{
"type": "upgrade_required",
"message": "This service requires the use of TLS."
}429 - Rate limit error
요청 수가 속도 제한을 초과하면 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)가 됩니다.
참고: 너무 많은 요청에 대해 오류가 발생하면 수정된 요청을 시도하기 전에 최소 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 - Internal server error
Rapid API 또는 업스트림 시스템 내의 오류를 반환합니다. 특정 작업이 주어지면 메시지 필드의 지침을 따르고, 그렇지 않으면 동일한 affiliate_reference_id로 요청을 다시 시도해 주세요.
Rapid API 는 문제를 감지했지만 정확한 문제가 무엇인지 더 구체적으로 알 수 없는 경우 HTTP 500으로 응답합니다. 모든 파트너는 때때로 Rapid API 사용 시 코드 500 응답을 예상해야 합니다.
HTTP 500 오류는 시리아와 같이 지원되지 않는 POS가 사용될 때도 발생할 수 있습니다.
예약 생성 또는 예약 취소 이외의 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, 또는 다운스트림 서비스가 현재 요청을 처리할 수 없음을 나타냅니다. 일시적인 과부하부터 공급업체와의 연결이 끊어지는 경우까지 여러 가지 이유가 있을 수 있습니다.
예약 만들기 또는 예약 취소 이외의 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 - Gateway time out
HTTP 504 오류는 일반적으로 Rapid API 에서 발생하는 것이 아니라 클라우드 또는 엣지 인프라에서 발생하며 트랜잭션 중에 네트워크 인프라의 항목(예: 로드 밸런서)이 실패했음을 나타냅니다. 일반적으로 일시적인 이벤트입니다.
참고: 타임아웃은 일정 생성 전후에 발생할 수 있으므로 항상 일정가 생성되었는지 확인하시기 바랍니다.
HTTP 504(및 502) 오류 응답은 Rapid API's JSON 유형/메시지 객체 쌍이 아닌 HTML 형식입니다. 이는 이러한 오류가 다음에서 생성되지 않았음을 나타내는 또 다른 표시입니다. 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%의 예약 통화에서 코드 50배 오류가 발생하여 실패할 것으로 예상됩니다.
시간이 지나면 임계값을 직접 계산할 수 있을 것입니다. 임계값이 하루에 5개로 설정되어 있더라도 예를 들어 5분 이내에 500 오류가 두 번 발생하면 Rapid API 지원팀에 문의하여 원인을 확인해야 합니다.
로그
Rapid API 지원팀에서 요청/응답 로그를 요청하는 경우 다음을 제공해 주세요:
- API 응답 헤더의
Transaction-Id값. 이 값은 심층 조사에 매우 중요합니다. - API 요청 및 응답 로그 모두. 요청 로그에는 사용된 전체 엔드포인트 URL이 포함되어야 합니다. 응답 로그에는 반환된 HTTP 코드, 전체 응답 데이터 및 반환된 모든 헤더가 포함되어야 합니다.
point_of_sale매개변수와 예약 가능 여부 응답이 있는 예약 가능 여부 API 요청. 이렇게 하면 지원팀에서 사용 중인 Rapid API 계정과 프로필을 식별할 수 있습니다.- 각 예약 요청에 대한 예약 API 요청 헤더와 권한 부여 헤더(API키, 서명, 타임스탬프 포함).
- 요청 로그의 예약 요청 URL 및 토큰
- 예약 호출이 작동했는지 또는 실패했는지에 관계없이 예약 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 형식은 데이터에 불필요한 줄 바꿈 문자를 추가합니다.
부록
빠르게 해결되지 않은 예약 예시
예약 확정 예시
예약 실패 예시
