Formato e códigos de erro da API

Quando uma requisição à API falha, o Omnifox retorna um envelope de erro consistente em todos os endpoints, para que sua integração trate erros de forma programática sem precisar interpretar texto livre.

Formato do erro

{
  "code": 42200,
  "message": "The given data was invalid.",
  "details": {
    "email": ["O campo email deve ser um endereço válido."]
  }
}

• code: inteiro legível por máquina, útil para ramificar lógica sem depender do texto de message (que pode variar conforme o idioma do usuário).
• message: texto legível para humanos.
• details: objeto opcional com informação estruturada extra (por exemplo, erros de validação por campo).

Tabela de códigos

Exemplo: tratando um 422 na sua integração

const res = await fetch('https://app.omnifox.io/api/v1/contacts', { method: 'POST', ... });
const body = await res.json();

if (!res.ok) {
  if (body.code === 42200) {
    console.log('Erros de validação:', body.details);
  } else if (body.code === 42900) {
    console.log('Limite de taxa, tentar novamente mais tarde');
  }
}

Dicas

• Ramifique sua lógica de nova tentativa pelo code, não apenas pelo status HTTP: um 400/422 não deve ser reenviado automaticamente (é um erro do cliente), enquanto um 429/500 deve, com backoff.
• Sempre registre details nos logs da sua integração: é a pista mais rápida para depurar uma rejeição da API.

Solução de problemas

• details vem null: acontece em erros genéricos (401, 403, 404, 500) que não carregam informação estruturada adicional; o message é a única pista.
• Recebi um status HTTP que não está na tabela: para status não mapeados, code é calculado como status * 100 (ex.: um 418 retornaria 41800).