Tratamento de Erros e Exceções na API

:::important PADRÃO DE RETORNO DE ERROS DE NEGÓCIO Ao integrar com a Web API Aéreo, é vital entender a distinção entre Erros de Transporte/Autenticação e Erros de Negócio das Companhias Aéreas. :::

---

1. Códigos de Status HTTP

A API utiliza códigos HTTP padrão para problemas de infraestrutura e segurança:

Status HTTP	Cenário	Causa Comum
200 OK	Requisição processada com sucesso	A requisição chegou aos provedores e foi processada (verifique o campo Exception no corpo!).
400 Bad Request	Parâmetros inválidos	JSON malformado, tipos incompatíveis ou campos obrigatórios ausentes.
401 Unauthorized	Falha de autenticação	developer-token inválido, data expirada no developer-access-code ou chave incorreta.
500 Internal Error	Erro interno do servidor	Falha inesperada de infraestrutura ou falha de conectividade de rede com GDSs.

---

2. A Estrutura de Erro de Negócio (No Corpo HTTP 200)

Diferente de APIs web tradicionais, quando uma companhia aérea rejeita uma operação (por exemplo: voo esgotado, tarifa que expirou, cartão recusado ou localizador inexistente), a API retorna HTTP 200 OK, indicando que a comunicação com o ecossistema aéreo foi concluída, e inclui os detalhes do erro no objeto Exception ou na lista ExceptionPorSistema.

Exemplo de Resposta com Erro de Negócio

{
  "Data": "2026-10-15T14:32:00",
  "SessaoExpirada": false,
  "ViagensTrecho1": null,
  "Exception": {
    "Message": "A tarifa selecionada não está mais disponível no fornecedor."
  },
  "ExceptionPorSistema": [
    {
      "Sistema": 1,
      "SistemaDescricao": "Sabre",
      "Mensagem": "CLASS NOT AVAILABLE"
    },
    {
      "Sistema": 2,
      "SistemaDescricao": "Gol Direto",
      "Mensagem": "Tarifa esgotada para o horário solicitado"
    }
  ]
}

---

3. Padrão Recomendado de Tratamento (Código Defensivo)

Ao consumir qualquer endpoint da API aérea, seu código deve seguir a seguinte validação:

Exemplo em JavaScript / Node.js

async function chamarApiAerea(url, payload, headers) {
  const response = await axios.post(url, payload, { headers });

  // 1. Verifica se a resposta HTTP foi 200
  if (response.status !== 200) {
    throw new Error(`Erro HTTP ${response.status}: ${response.statusText}`);
  }

  const data = response.data;

  // 2. Verifica se a resposta contém erro de negócio
  if (data.Exception && data.Exception.Message) {
    console.error('Falha de negócio na Cia Aérea:', data.Exception.Message);
    if (data.ExceptionPorSistema && data.ExceptionPorSistema.length > 0) {
      console.error('Detalhes por sistema:', data.ExceptionPorSistema);
    }
    throw new Error(data.Exception.Message);
  }

  // 3. Sucesso garantido: prossegue com os dados
  return data;
}

Exemplo em Python

import requests

def executar_chamada_aerea(url, payload, headers):
    resp = requests.post(url, json=payload, headers=headers)
    resp.raise_for_status() # Lança erro se HTTP 4xx ou 5xx
    
    data = resp.json()
    
    # Validação do erro de negócio no corpo da mensagem
    if data.get("Exception") and data["Exception"].get("Message"):
        mensagem_erro = data["Exception"]["Message"]
        raise RuntimeError(f"Erro do fornecedor aéreo: {mensagem_erro}")
        
    return data