Tratamento de Erros

Formatos diferentes por versão

A API v1 e a API v2 retornam erros em formatos completamente distintos. Certifique-se de tratar cada versão separadamente no seu código.

API v2 — RFC 7807 Problem Details

A API v2 segue o padrão RFC 7807 Problem Details for HTTP APIs. Todos os erros retornam um objeto JSON com os seguintes campos:

{
  "type": "urn:frota162-api-v2:error:{tipo}",
  "title": "Título legível do erro",
  "status": 401,
  "detail": "Descrição específica do problema nesta requisição",
  "instance": "/v2/driver-indications/SP-2024-000001",
  "traceId": "abc123def456"
}

Campo	Tipo	Descrição
`type`	string	URN única que identifica o tipo de erro — estável entre versões
`title`	string	Título do erro — não muda entre ocorrências do mesmo tipo
`status`	number	Código HTTP da resposta
`detail`	string	Descrição específica desta ocorrência (pode variar)
`instance`	string	Caminho da requisição que gerou o erro
`traceId`	string	ID de rastreamento — inclua ao contatar suporte

Tipos de erro da API v2

`type`	Status HTTP	Quando ocorre
`urn:frota162-api-v2:error:unauthorized`	`401`	Headers `Authorization` ou `Key` ausentes, ou esquema inválido
`urn:frota162-api-v2:error:authentication-failed`	`401`	Assinatura HMAC inválida ou token não reconhecido
`urn:frota162-api-v2:error:not-found`	`404`	Recurso não encontrado (ex: AIT inexistente)
`urn:frota162-api-v2:error:validation-error`	`400`	Campos obrigatórios ausentes ou formato inválido
`urn:frota162-api-v2:error:rate-limit-exceeded`	`429`	Limite de requisições atingido
`urn:frota162-api-v2:error:internal-server-error`	`500`	Erro inesperado no servidor
`urn:frota162-api-v2:error:external-api-error`	`502`	Falha na comunicação com serviço externo

Exemplos

Header de autenticação ausente (`401`)

{
  "type": "urn:frota162-api-v2:error:unauthorized",
  "title": "Unauthorized Access",
  "status": 401,
  "detail": "Missing required header: Authorization",
  "instance": "/v2/driver-indications",
  "traceId": "abc123"
}

Assinatura HMAC inválida (`401`)

{
  "type": "urn:frota162-api-v2:error:authentication-failed",
  "title": "Authentication Failed",
  "status": 401,
  "detail": "Invalid Key header",
  "instance": "/v2/driver-indications",
  "traceId": "abc123"
}

Recurso não encontrado (`404`)

{
  "type": "urn:frota162-api-v2:error:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Driver indication with AIT 'SP-2024-000001' not found",
  "instance": "/v2/driver-indications/SP-2024-000001",
  "traceId": "abc123"
}

Validação de payload (`400`)

{
  "type": "urn:frota162-api-v2:error:validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid or missing parameters",
  "instance": "/v2/driver-indications",
  "traceId": "abc123"
}

Estratégia de retry — API v2

Status	`type`	Fazer retry?	Ação recomendada
`400`	`validation-error`	Não	Corrigir o payload
`401`	`unauthorized`	Não	Verificar headers `Authorization` e `Key`
`401`	`authentication-failed`	Não	Recalcular assinatura HMAC
`404`	`not-found`	Não	Confirmar o identificador do recurso
`429`	`rate-limit-exceeded`	Sim	Aguardar e retentar (ver header `Retry-After`)
`500`	`internal-server-error`	Sim	Backoff exponencial (1s → 2s → 4s)
`502`	`external-api-error`	Sim	Backoff exponencial

Exemplo de tratamento em Node.js — API v2

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

  if (!resposta.ok) {
    const { type, title, detail, traceId } = dados;

    switch (type) {
      case 'urn:frota162-api-v2:error:unauthorized':
      case 'urn:frota162-api-v2:error:authentication-failed':
        throw new Error(`Autenticação inválida: ${detail}`);

      case 'urn:frota162-api-v2:error:not-found':
        throw new Error(`Recurso não encontrado: ${detail}`);

      case 'urn:frota162-api-v2:error:validation-error':
        throw new Error(`Dados inválidos: ${detail}`);

      case 'urn:frota162-api-v2:error:rate-limit-exceeded': {
        const retryAfter = parseInt(resposta.headers.get('Retry-After') || '60');
        await sleep(retryAfter * 1000);
        return chamarApiV2(url, opcoes);
      }

      case 'urn:frota162-api-v2:error:internal-server-error':
      case 'urn:frota162-api-v2:error:external-api-error':
        await sleep(1000);
        return chamarApiV2(url, opcoes);

      default:
        throw new Error(`Erro da API v2 [${resposta.status}] — ${detail} (traceId: ${traceId})`);
    }
  }

  return dados;
}

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 v2:

A URL e método HTTP da requisição
O campo type do erro retornado
O campo traceId retornado
O campo detail e o status HTTP

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

API v2 — RFC 7807 Problem Details

Tipos de erro da API v2

Exemplos

Header de autenticação ausente (401)​

Assinatura HMAC inválida (401)​

Recurso não encontrado (404)​

Validação de payload (400)​

Estratégia de retry — API v2

Exemplo de tratamento em Node.js — API v2

API v1 — Formato fbk_xxx​

Formato de resposta​

Códigos de retorno (fbk_xxx)​

Exemplos por situação​

Token inválido (fbk_001)​

Recurso não encontrado (fbk_004)​

Operação bem-sucedida (fbk_200)​

Dados inválidos (fbk_400)​

Erro interno (fbk_500)​

Estratégia de retry​

Exemplo de tratamento em Node.js​

Contato com suporte​