Erros e status HTTP

Formato padrão

Todas as respostas de erro seguem o mesmo envelope:


{
  "error": {
    "code": "CODIGO_DO_ERRO",
    "message": "Descrição legível do erro",
    "correlationId": "uuid-de-rastreamento",
    "details": {}
  }
}

Campo	Tipo	Descrição
`code`	`string`	Código identificador do erro
`message`	`string`	Mensagem descritiva do erro
`correlationId`	`string`	UUID para rastreamento do request
`details`	`object`	Detalhes adicionais (quando disponível)

O campo correlationId é retornado pela Busca de Voos. Nas respostas do Histórico de Preços o envelope traz apenas code, message e details. Sempre trate correlationId como opcional.

Códigos de erro — Busca de Voos

Código	Descrição
`HTTP_ERROR`	Erro HTTP genérico
`VALIDATION_ERROR`	Erro de validação no body da requisição
`UNAUTHORIZED`	Falha de autenticação
`NOT_FOUND`	Recurso não encontrado
`QUOTA_EXCEEDED`	Quota de uso excedida
`INTERNAL_ERROR`	Erro interno inesperado
`NOT_ACCEPTABLE`	Media type não suportado
`AIRLINE_PROVIDER_ERROR`	Erro na comunicação com provedor da companhia

Códigos de erro — Histórico de Preços

HTTP	Código	Descrição
`401`	`AUTHENTICATION_ERROR`	API key ausente ou inválida
`403`	`AUTHORIZATION_ERROR`	API key inativa ou sem acesso ao produto
`406`	`UNSUPPORTED_VERSION`	Versão informada no header `Accept` não é suportada
`422`	`VALIDATION_ERROR`	Validação de parâmetros falhou (valores inválidos ou ausentes)
`500`	`INTERNAL_ERROR`	Erro interno inesperado

Os dois produtos usam conjuntos de códigos diferentes para situações equivalentes — por exemplo, falha de autenticação é UNAUTHORIZED na Busca de Voos e AUTHENTICATION_ERROR no Histórico de Preços. Trate os códigos por produto, e use o status HTTP quando precisar de uma lógica comum aos dois.

Códigos de status HTTP

Código	Significado	Quando ocorre
`200`	OK	Requisição processada com sucesso
`400`	Bad Request	Parâmetros inválidos
`401`	Unauthorized	API Key ausente, inválida ou não encontrada
`402`	Payment Required	Quota excedida ou API Key inativa/bloqueada
`403`	Forbidden	API Key sem acesso ao produto solicitado
`404`	Not Found	Recurso não encontrado
`406`	Not Acceptable	Header `Accept` com media type não suportado
`422`	Unprocessable Entity	Erro de validação no corpo ou nos parâmetros
`500`	Internal Server Error	Erro inesperado no servidor

Exemplo — erro de validação


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "errors": [
        {
          "field": "query -> cabin_type",
          "message": "Input should be 'ECONOMY' or 'BUSINESS'",
          "type": "enum"
        }
      ]
    }
  }
}

Exemplo — erro de autenticação


{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "API key não informada. Envie-a pelo header x-api-key."
  }
}

Exemplo — erro de autorização (produto não contratado)


{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Sua API key não possui acesso a este produto. Entre em contato com o suporte para contratar."
  }
}

Ao reportar um problema para o suporte, envie sempre o correlationId da resposta — ele permite rastrear a requisição exata nos nossos logs.