Tratamento de Erros

---

API v1 — Formato fbk_xxx

Todas as respostas da API Frota162 v1 seguem um formato consistente com os campos message, error e code.

Formato de resposta

Sucesso:

{
  "message": "...",
  "error": false,
  "code": "fbk_200"
}

Erro:

{
  "message": "Descrição do erro",
  "error": true,
  "code": "fbk_001"
}

Códigos de retorno (fbk_xxx)

Código	Tipo	Descrição
fbk_001	Autenticação	Usuário/token não encontrado ou inválido
fbk_002	Autorização	Sem permissão para a empresa
fbk_003	Validação	Campo obrigatório ausente
fbk_004	Recurso não encontrado	Recurso não existe ou não pertence à conta
fbk_006	URL inválida	URL do webhook inválida
fbk_008	Duplicata	Webhook com mesma url + event_id já cadastrado
fbk_200	Sucesso	Operação concluída com sucesso
fbk_400	Requisição inválida	Dados enviados inválidos ou mal formatados
fbk_500	Erro interno	Erro inesperado no servidor

Exemplos por situação

Token inválido (fbk_001)

{
  "message": "Não autorizado",
  "error": true,
  "code": "fbk_001"
}

Causa: Token ausente, inválido ou assinatura HMAC incorreta.

Como resolver: Verifique se o ACCESS_TOKEN está correto e recalcule a assinatura HMAC. Consulte Autenticação HMAC.

---

Recurso não encontrado (fbk_004)

{
  "message": "Condutor não pertence a empresa que tenha acesso",
  "error": true,
  "code": "fbk_004"
}

Causa: O recurso solicitado não existe ou não pertence à conta autenticada.

Como resolver: Confirme o ID do recurso listando os registros disponíveis.

---

Operação bem-sucedida (fbk_200)

{
  "message": "Condutor desabilitado com sucesso",
  "error": false,
  "code": "fbk_200"
}

---

Dados inválidos (fbk_400)

{
  "message": "O campo placa é obrigatório",
  "error": true,
  "code": "fbk_400"
}

Causa: Campo obrigatório ausente ou dado em formato incorreto.

Como resolver: Verifique os campos obrigatórios do endpoint na documentação.

---

Erro interno (fbk_500)

{
  "message": "Erro inesperado",
  "error": true,
  "code": "fbk_500"
}

Causa: Erro inesperado no servidor.

Como resolver: Tente novamente após alguns segundos. Se persistir, entre em contato com suporte@frota162.com.br.

Estratégia de retry

Código / Situação	Fazer retry?	Ação recomendada
fbk_001 (token inválido)	Não	Revisar ACCESS_TOKEN e recalcular HMAC
fbk_002 (sem permissão)	Não	Verificar se o token tem acesso à empresa
fbk_003 (campo ausente)	Não	Corrigir os campos obrigatórios
fbk_004 (não encontrado)	Não	Confirmar o ID do recurso
fbk_400 (dados inválidos)	Não	Corrigir os dados enviados
fbk_500 (erro interno)	Sim	Backoff exponencial (1s → 2s → 4s)
HTTP 429 (rate limit)	Sim	Aguardar e retentar

Exemplo de tratamento em Node.js

async function chamarApi(url, opcoes) {
  const resposta = await fetch(url, opcoes);
  const dados = await resposta.json();

  if (dados.error) {
    switch (dados.code) {
      case 'fbk_001':
        throw new Error('Token inválido. Verifique o ACCESS_TOKEN e recalcule o HMAC.');
      case 'fbk_004':
        throw new Error('Recurso não encontrado: ' + dados.message);
      case 'fbk_400':
        throw new Error('Dados inválidos: ' + dados.message);
      case 'fbk_500':
        await sleep(1000);
        return chamarApi(url, opcoes);
      default:
        throw new Error('Erro da API: ' + dados.message);
    }
  }

  return dados.message;
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Contato com suporte

Se encontrar erros persistentes, entre em contato em suporte@frota162.com.br informando:

Para erros da API v1:

• A URL e método HTTP da requisição
• O código de erro (fbk_xxx) retornado
• A mensagem de erro completa
• Timestamp da ocorrência