Respostas de erro comuns

Os serviços da nossa API compartilham os formatos comuns de respostas, mensagens e códigos de erro a seguir. Consulte cada página de documentação para analisar as respostas de erro que são exclusivas para cada serviço.

Recomendações de tratamento de erros da Rapid

Lógica de tratamento de erros

• Plataformas e parceiros precisam ter uma lógica para o tratamento de erros das respostas de compras e reservas para lidar com erros da Rapid.
• Sempre use um affiliate_reference_id exclusivo para cada solicitação de reserva, a menos que especificado nas observações a seguir.
• Parceiros precisam analisar e atualizar a lógica para o tratamento de erros com frequência, em particular no caso das solicitações de reserva.
• Todas as respostas da Rapid têm um código HTTP correspondente: confira na lista abaixo.

Tempo limite de conexão ou de comunicação

É recomendável ter uma configuração de tempo limite de 90 segundos para conexão à API no caso das solicitações de reserva. Embora não haja uma recomendação definida para outras APIs, já que o tempo limite não gera perdas financeiras, convém usar uma configuração semelhante. No entanto, alguns parceiros talvez decidam usar um tempo limite de conexão menor em chamadas de disponibilidade de compras.

Se o parceiro não receber uma resposta em 120 segundos, ela não vai chegar. Isso ocorre porque a EPS Rapid tem as próprias configurações de tempo limite, e 120 segundos é o limite final da API. Depois disso, a Rapid vai retornar um erro 5xx.

Em alguns casos, a Rapid não aceita o processo HTTP Expect: 100-Continue. Parceiros podem enfrentar problemas de conexão para tentar conectar servidores com o processo, sobretudo em cURL, C#/.NET e outras linguagens de codificação que seguem o processo por padrão.

Observação: o gateway HTTP 504 atingir o tempo limite não significa que a Rapid também o atingiu. Nesses casos, um serviço de infraestrutura falhou, ou a Rapid está agindo como gateway para outro serviço downstream e define um tempo limite para esse serviço. É esse tempo limite que foi acionado, e a EPS precisa relatá-lo como um 504. Se o 504 acontecer para uma chamada de reserva, verifique se a reserva foi criada ou não usando a Itinerary Retrieve (affiliate_reference_id+e-mail), já que o problema downstream pode ocorrer antes (por exemplo, comunicação do hotel, servidor de pagamentos) ou após a criação (por exemplo, gestão de finanças da EPS). Além disso, verifique se a conexão com a internet está estável. Um comando Traceroute pode ajudar a identificar problemas de conectividade.

Tratamento de erros 5xx de reserva e recuperação

Um erro (status 5xx) ou tempo limite na reserva não significa que ela seja inválida e não deve ser interpretado dessa forma. Como o erro pode ter ocorrido após a criação da reserva, é recomendável usar Itinerary Retrieve com affiliate_reference_id+e-mail para verificar o status da reserva.

Erros retornados em 90 segundos não indicam o status final da reserva. Em geral, a maioria das reservas vai ser confirmada dentro de 13 a 30 segundos, mas algumas podem levar até 90 segundos.

Os parceiros podem implementar a lógica para verificar o status da reserva 3 vezes em um período de 90 segundos. A maioria das respostas vai ser confirmada nos primeiros 30 segundos, e os parceiros podem fazer isso sem esperar os 90 segundos. Se uma resposta final não foi recebida, os parceiros podem recuperar de novo após 60 segundos e, por fim, depois de 90 segundos para fazer a validação.

Use uma chamada da API de recuperação e confirme mais uma vez os resultados da reserva (resposta HTTP 200 ou HTTP 404).

A resposta de recuperação retorna informações sobre espera e retomada

Às vezes, após uma reserva ser feita, a resposta da Itinerary Retrieve vai retornar dados que parecem ser de uma reserva de espera e retomada. Portanto, em vez das informações de reserva esperadas (quartos, multas por cancelamento etc.), a resposta vai apresentar apenas os tokens necessários para uma situação de espera e retomada.

Resposta de exemplo:

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

A razão é que a reserva, embora válida, ainda tem um sinalizador pendente, que vai acabar desaparecendo em alguns minutos. Portanto, as solicitações Itinerary Retrieve precisam ser repetidas até que a reserva seja concluída.

Explicação sobre os erros com estrutura de vários níveis

A resposta da API pode dividir um erro em vários níveis, em que o erro de um único nível pode não explicar todos os detalhes. Iterar as informações em todos os níveis vai ajudar a esclarecer e solucionar melhor o erro.

Resposta de exemplo:

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

Códigos de resposta HTTP

400 - Bad Request

Retorna caso a sua solicitação esteja corrompida ou tenha valores impróprios.

Os erros do código 400 Bad Request indicam um problema com o cabeçalho de reserva da solicitação. A resposta de erro vai incluir o campo de matriz do erro real no cabeçalho da solicitação de reserva, que é inválido. O cabeçalho da reserva é formado por várias matrizes e submatrizes, como quartos e pagamentos. A matriz geral é o corpo. Assim, body.email indica o parâmetro de e-mail para o corpo do cabeçalho.

Observação: a matriz de quartos do cabeçalho de reserva precisa ter o mesmo número de entradas que os quartos solicitados na chamada de disponibilidade.

Um erro 400 Bad Request denominado Tomcat Exception Report é retornado quando os parâmetros da solicitação são excessivamente grandes, geralmente nas APIs de conteúdo de propriedade e disponibilidade. Para evitar esse erro, reduza o número de propriedades ou remova parâmetros desnecessários da solicitação.

Respostas de exemplo:

Idiomas sem suporte:

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

Valor ausente da versão:

{
  "type": "version.required",
  "message": "You have not specified a version, the supported versions are: [1, 2]",
  "fields": [
    {
      "name": "version",
      "type": "path",
      "value": "missing"
    }
  ]
}

Valor inválido da versão:

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

Retorna se o seu cabeçalho de autorização HTTP não for encontrado ou não puder ser analisado. Cada solicitação de qualquer serviço da Rapid API deve incluir o hash SHA-512 sem sal da concatenação da sua chave de API + segredo compartilhado + carimbo de data/hora UNIX em segundos. Consulte a nossa página de autorização de assinatura para detalhes completos.

Exemplo de resposta 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

Retorna quando o seu cabeçalho de autorização HTTP é válido, mas você não tem permissão para acessar o recurso solicitado.

Exemplo de resposta 403 Forbidden:

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

404 - Not found

Retorna se o recurso solicitado da API não pode ser encontrado. Verifique o URL da sua solicitação em relação aos nossos exemplos documentados.

A API de geografia e a API de conteúdo também usam as respostas 404 para indicar quando os arquivos de geografia ou conteúdo específicos solicitados ou recursos não podem ser localizados. Consulte os exemplos completos nas respectivas páginas de documentação.

O código 404 após uma recuperação de itinerário indica que a reserva não foi encontrada. Se a solicitação de recuperação foi usada devido a um erro de reserva, isso indica que a reserva não foi criada. No entanto, parceiros precisam verificar se os parâmetros da solicitação da API da Itinerary Retrieve são válidos. Por isso, confirme que o affiliate_reference_id de recuperação, o e-mail e/ou número do itinerário estão corretos. Além disso, se a chamada de recuperação da API foi feita a menos de 90 segundos da chamada de reserva, tente a recuperação de novo, dessa vez garantindo que esse tempo seja respeitado.

Resposta de exemplo:

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

409 - Price mismatch

Muitas propriedades e redes usam preços dinâmicos, também conhecidos como "preços por demanda". Isso significa que os preços variam de acordo com os algoritmos de oferta e demanda. O Expedia Group recebe tarifas atualizadas de propriedades várias vezes por segundo, ou seja, as tarifas mudam com frequência.

É importante observar que, em geral, essa escolha é da propriedade, não da EPS. Além disso, como se usa cache em vários níveis para tarifas/disponibilidade, inclusive no nível do parceiro, pode haver várias camadas de latência nas reservas.

Uma incompatibilidade de preços (PMM, na sigla em inglês) é uma situação esperada e pode ocorrer por vários motivos, inclusive quando os sistemas estão degradados ou não refletem os preços atualizados inseridos pelas propriedades. Os parceiros precisam monitorar a frequência desses eventos e entrar em contato com o suporte da EPS caso a tarifa aumente de repente ou atinja um limite.

Se uma PMM ocorreu em várias propriedades/quartos ao mesmo tempo, verifique se houve degradação da Rapid.

Se uma PMM é retornada para a mesma tarifa/quarto durante um longo período, é provável que seja devido ao carregamento incorreto de tarifas pela propriedade. Entre em contato com o suporte técnico da EPS para verificar.

Para se recuperar de uma PMM, faça a chamada à Price Check API mais uma vez para receber um novo token de URL de reserva. É possível usar o mesmo affiliate_reference_id na chamada de reserva.

Resposta de exemplo:

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

Retorna quando o link da Rapid que está sendo seguido expirou, ou quando os quartos solicitados não estão mais disponíveis.

Muitas redes e propriedades hoteleiras têm links de comunicação direta com o Expedia Group. A comunicação síncrona é uma troca interativa que acontece em tempo real entre o Expedia Group e as propriedades/redes.

A reserva por comunicação síncrona ocorre quando a propriedade ou a rede fornece à EPS seu inventário de quartos (disponibilidade e preço), que a EPS gerencia, e as chamadas subsequentes de disponibilidade para compra e verificação de preço são feitas com base nesses dados. Então, no momento da reserva, uma chamada síncrona é feita à propriedade para reservar os quartos. Esse erro ocorre quando não há inventário suficiente para os quartos selecionados. Se for constatado que o inventário é insuficiente, a Rapid vai retornar a mensagem de erro do código 410.

Essa pode ser uma situação temporária, e uma nova tentativa pode encontrar os quartos disponíveis. Aguarde 90 segundos e verifique o status com uma solicitação de recuperação usando o mesmo affiliate_reference_id que foi enviado com a reserva. Se nenhuma reserva for encontrada, os usuários talvez tenham que escolher outra combinação de propriedade/quarto/tarifa/data.

Mensagens de erro que indicam inventário esgotado também podem ocorrer se a conexão com a propriedade está degradada e, por isso, a Rapid não tem indicação da disponibilidade real.

Resposta de exemplo:

Link expirado:

{
  "type": "link.expired",
  "message": "The link you followed has expired. Please request a new link."
}

Esgotado:

"type": "rooms_unavailable",
"message": "One or more requested rooms are unavailable."

426 - Upgrade required

Retorna se a solicitação não usar TLS (substitui SSL).

Resposta de exemplo:

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

429 - Rate limit error

Observação: se você receber um erro por muitas solicitações, aguarde pelo menos cinco minutos antes de tentar uma solicitação corrigida. Tentar de novo com mais frequência vai causar falhas repetidas devido ao tempo do cache.

O código de status 429 é retornado quando o número de solicitações excede um limite. Cada solicitação está sujeita a dois limites diferentes: aqueles em que uma integração está enviando solicitações em uma taxa acima do limite e aqueles em que os servidores do Expedia Group estão com uma carga acima do limite.

Quando um parceiro faz uma solicitação da API o Expedia Group, o servidor que a recebe verifica se a contagem de solicitações está dentro do limite. Se estiver, o processo vai continuar, e a contagem vai aumentar para o cliente. Se a contagem de solicitações feitas por um cliente exceder o limite, o servidor vai retornar uma resposta com um código de status HTTP 429 (too many requests).

O servidor pode, como outra opção, incluir um cabeçalho Rate-Limit-Day-Reset e Rate-Limit-Minute-Reset. Isso indica quanto tempo você precisa esperar antes de enviar a próxima solicitação. São as informações de data/hora de quando a próxima queda vai ocorrer, em microssegundos (não milissegundos).

Por exemplo, quando convertido em data/hora, o valor "15489792000000" resulta em Friday, February 1, 2019 12:00:00 AM (UTC).

Resposta de exemplo:

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

Retorna em caso de erro na Rapid API ou em sistemas upstream. Siga as instruções no campo de mensagem se uma ação específica for apresentada. Caso contrário, tente a sua solicitação de novo com o mesmo affiliate_reference_id.

A Rapid responde com HTTP 500 quando detecta um problema, mas não consegue especificar qual é a situação. De tempos em tempos, é normal que todos os parceiros recebam respostas do código 500 ao usar a Rapid.

Um erro HTTP 500 também pode ocorrer quando um ponto de venda incompatível é usado, como a Síria.

Se você recebeu o erro em uma resposta da API que não seja de criação de reserva ou cancelamento de reserva e não souber de alguma degradação, repita a solicitação mais tarde. A resposta pode incluir um cabeçalho Retry-After para indicar um intervalo mínimo, em segundos, antes de uma nova tentativa.

Se você recebeu o erro na resposta da API ao criar uma reserva:

• Aguarde 90 segundos e verifique o status com uma solicitação de recuperação usando o mesmo affiliate_reference_id que foi enviado com a reserva.
• Se nenhuma reserva for encontrada, ou você continuar recebendo o erro 500, tente fazer o processo de novo mais tarde.

Se você recebeu o erro na resposta da API ao cancelar uma reserva:

• Aguarde 90 segundos e verifique o status com uma solicitação da Itinerary Retrieve usando o itinerary_id conhecido.
• Se a reserva não foi cancelada, ou você continua recebendo o erro 500, repita a solicitação de cancelamento mais tarde.

Respostas de exemplo:

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

Em geral, o erro HTTP 503 é temporário e indica que a Rapid ou um serviço downstream não está conseguindo processar a solicitação no momento. Existem várias razões possíveis para isso, desde uma sobrecarga temporária até a perda da conexão com a propriedade.

Se você recebeu o erro em uma resposta da API que não seja de criação de reserva ou cancelamento de reserva e não souber de alguma degradação, repita a solicitação mais tarde. A resposta pode incluir um cabeçalho Retry-After para indicar um intervalo mínimo, em segundos, antes de uma nova tentativa.

Se você recebeu o erro na resposta da API ao criar uma reserva:

• O link de reserva da sua resposta de verificação de preço anterior expira após um breve período. Se você recebeu um código de erro HTTP 503 após a sua primeira tentativa, é provável que o link tenha expirado. Use um novo link e tente reservar outra vez.
• Se você receber um erro 503 na segunda tentativa, aguarde 90 segundos e verifique o status com uma solicitação de recuperação usando o mesmo affiliate_reference_id que foi enviado com a reserva.
• Se nenhuma reserva for encontrada ou você continuar recebendo o erro 503, repita o processo mais tarde.

Se você recebeu o erro na resposta da API ao cancelar uma reserva:

• Aguarde 90 segundos e verifique o status com uma solicitação da Itinerary Retrieve usando o itinerary_id conhecido.
• Se a reserva não foi cancelada, ou você continua recebendo o erro 503, repita a solicitação de cancelamento mais tarde.

Resposta de exemplo:

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

504 - Gateway time out

Em geral, o erro HTTP 504 não é da Rapid, mas da infraestrutura de nuvem ou borda. Além disso, indica que um item na infraestrutura de rede (como o balanceador de carga) falhou durante a transação. Isso costuma ser um evento temporário.

O tempo limite pode ser atingido antes ou depois da criação do itinerário. Portanto, sempre verifique se o itinerário foi criado ou não.

As respostas de erro HTTP 504 (e 502) estão no formato HTML, e não no par de objetos tipo/mensagem JSON da Rapid. Essa é outra indicação de que esses erros não são gerados pela Rapid.

Resposta de exemplo:

<html>
<head><title>504 Gateway Time-out</title></head>
<body>
<center><h1>504 Gateway Time-out</h1></center>
</body>
</html>

Taxa-limite de respostas de erro

Para estabelecer os próprios valores de limite, parceiros precisam medir a taxa diária dos seguintes códigos de resposta: 409, 410, 500, 503 e 504. Se o limite for excedido, vai ser necessário entrar em contato com o suporte da EPS.

A EPS não tem nenhum valor-limite definido, porque isso depende da plataforma em que os parceiros estão e fazem vendas, bem como de outros fatores. Conhecimento da plataforma é essencial para determinar por que algumas respostas de erro ocorrem. A orientação é esperar que até 5% a 6% das chamadas de reserva falhem com um erro de código 50xx durante um período diário ou semanal.

Com o tempo, parceiros devem ser capazes de calcular os próprios valores de limite e não devem apenas buscar um aumento diário repentino. Mesmo se um limite de 5 por dia for definido, ter 2 erros 500 em intervalos de 5 minutos, por exemplo, pode ser um motivo para falar com o suporte da EPS.

Logs

Se a EPS solicitar os logs de solicitação/resposta, tente fornecer o seguinte:

• O valor Transaction-Id no cabeçalho de resposta da API. Isso é vital para investigações mais profundas.
• Tanto os logs de solicitação quanto os de resposta da API. Os logs de solicitação precisam incluir o URL completo do ponto de extremidade usado. Os logs de resposta precisam incluir o código HTTP retornado, os dados de resposta completos e todos os cabeçalhos retornados.
• Solicitação à Availability API com o parâmetro point_of_sale, bem como resposta de disponibilidade. Assim, o suporte da EPS vai identificar a conta e o perfil da Rapid que está sendo usado.
• Cabeçalho de solicitação à Booking API e cabeçalho de autorização (com APIKey, assinatura e carimbo data/hora) para cada solicitação de reserva.
• O URL e o token da solicitação de reserva nos logs de solicitação.
• A Itinerary Retrieve feita após uma chamada de reserva à API, com falha ou não.

Inclua a solicitação e a resposta JSON completas. Uma string JSON precisa estar entre aspas duplas. Portanto, não é necessário incluir o caractere de escape de barra invertida na frente do caractere de aspas duplas.

Use o caractere de escape de barra invertida na frente de aspas duplas apenas quando precisar que elas façam parte da string.

Resposta de exemplo:

"spokenwords": "He said "hello world""

Não coloque os logs no formato PDF. Às vezes, o suporte e os desenvolvedores da EPS copiam/colam dados de log em ferramentas internas, e o formato PDF adiciona caracteres de avanço de linha desnecessários.

Anexo

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