Formato e códigos de erro da API
Como interpretar o envelope de erro da API do Omnifox e seus códigos numéricos.
Veja este passo no vídeo · Escopos em ação: o erro 403
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 demessage(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
| Status HTTP | code |
Significado |
|---|---|---|
| 400 | 40000 | Requisição malformada |
| 401 | 40100 | Não autenticado (token ausente/expirado) |
| 403 | 40300 | Proibido (sem permissão ou recurso não habilitado no plano) |
| 404 | 40400 | Recurso não encontrado |
| 409 | 40900 | Conflito (ex.: estado incompatível) |
| 422 | 42200 | Erro de validação |
| 429 | 42900 | Limite de taxa excedido |
| 500 | 50000 | Erro interno do servidor |
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
detailsnos logs da sua integração: é a pista mais rápida para depurar uma rejeição da API.
Solução de problemas
detailsvemnull: acontece em erros genéricos (401, 403, 404, 500) que não carregam informação estruturada adicional; omessageé a única pista.- Recebi um status HTTP que não está na tabela: para status não mapeados,
codeé calculado comostatus * 100(ex.: um 418 retornaria41800).
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.