Erros e códigos de resposta

A API usa os códigos de status HTTP para dizer se a requisição deu certo. Códigos 2xx indicam sucesso; 4xx, um problema na requisição; 5xx, um problema inesperado na Avoei.

Códigos que a API retorna

Código	Significado	Quando acontece	Tentar de novo?
200	Sucesso	A requisição deu certo. Listas sem resultado também retornam 200, com data.data vazio.	—
304	Não modificado	Você enviou If-None-Match e o conteúdo não mudou desde a resposta anterior. A resposta não traz corpo.	—
401	Não autenticado	O token não foi enviado, é inválido ou foi revogado.	Não. Corrija o token.
404	Não encontrado	A viagem não existe ou não está publicada, a agência não cadastrou a empresa, o endereço da agência está errado ou a assinatura da agência está vencida ou inativa.	Não.
405	Método não permitido	A requisição usou um método diferente de GET. A API é somente de leitura.	Não.
422	Parâmetro inválido	Um filtro, uma ordenação ou uma paginação tem valor inválido.	Não. Corrija o parâmetro.
429	Muitas requisições	O limite de requisições por minuto foi excedido.	Sim, depois de esperar.
500	Erro inesperado	Algo deu errado na Avoei.	Sim, com pausa entre as tentativas.

A API não retorna 400 nem 403 nesta versão.

Formato dos erros

A maioria dos erros usa o envelope padrão, com success igual a false. Duas exceções, 401 e 429, trazem só message.

401 — não autenticado

{
  "message": "Unauthenticated."
}

Veja como resolver em Autenticação.

404 — não encontrado

Ao consultar uma viagem ou a empresa que não existe:

{
  "success": false,
  "message": "Travel not found",
  "data": null,
  "errors": [],
  "status": 404
}

Uma viagem em rascunho ou arquivada também retorna 404: para a API, ela não existe. Se o 404 vier de um endereço de agência inválido, a resposta não segue o envelope. Confira o endereço.

422 — parâmetro inválido

O campo errors é um objeto: cada chave é o nome do parâmetro com problema, e o valor é a lista de mensagens sobre ele. Um parâmetro válido não aparece.

{
  "success": false,
  "message": "The given data was invalid.",
  "data": [],
  "errors": {
    "per_page": ["O campo per page deve ser entre 1 e 50."],
    "sort": ["O campo sort selecionado é inválido."]
  },
  "status": 422
}

observação

Use as chaves de errors (per_page, sort) para saber qual parâmetro corrigir. O texto das mensagens é escrito para pessoas e pode mudar; não o compare no seu código.

429 — muitas requisições

{
  "message": "Too Many Attempts."
}

A resposta traz o cabeçalho Retry-After, com o número de segundos a esperar, e X-RateLimit-Reset, com o momento em que a janela reabre. Veja Limites de requisições.

500 — erro inesperado

{
  "success": false,
  "message": "Internal Server Error",
  "data": [],
  "errors": [],
  "status": 500
}

O erro é registrado automaticamente na Avoei. Se ele persistir, entre em contato com o suporte e informe o horário aproximado e o endereço que você chamou.

Como o seu sistema deve reagir

1. Decida pelo código HTTP. Não dependa do texto de message.
2. Não repita 401, 404, 405 ou 422. Nesses casos, repetir a mesma requisição dá o mesmo resultado. Corrija a causa.
3. Repita 429 e 500 com pausa. No 429, espere o tempo de Retry-After. No 500, espere alguns segundos e aumente a pausa a cada nova tentativa, com um número máximo de tentativas.
4. Registre o erro com o código, o endereço chamado e o horário, para facilitar o diagnóstico.

const response = await fetch(url, { headers });

if (response.status === 429) {
  const seconds = Number(response.headers.get('Retry-After') ?? 60);
  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  // tente de novo
} else if (response.status === 422) {
  const { errors } = await response.json();
  console.error('Parâmetros inválidos:', Object.keys(errors));
}