Formato y códigos de error de la API

Cuando una solicitud a la API falla, Omnifox devuelve un sobre de error consistente en todos los endpoints, para que tu integración pueda manejar errores de forma programática sin tener que parsear texto libre.

Formato del error

{
  "code": 42200,
  "message": "The given data was invalid.",
  "details": {
    "email": ["El campo email debe ser una dirección válida."]
  }
}

• code: entero legible por máquina, útil para bifurcar lógica sin depender del texto de message (que puede variar según el idioma del usuario).
• message: texto legible para humanos.
• details: objeto opcional con información estructurada extra (por ejemplo, errores de validación por campo).

Tabla de códigos

Ejemplo: manejar un 422 en tu integración

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('Errores de validación:', body.details);
  } else if (body.code === 42900) {
    console.log('Rate limit, reintentar más tarde');
  }
}

Consejos

• Bifurcá tu lógica de reintentos por code, no por el HTTP status únicamente: por ejemplo, un 400/422 no se debe reintentar automáticamente (es un error del cliente), pero un 429/500 sí, con backoff.
• Guardá siempre details en tus logs de integración: es la pista más rápida para depurar un rechazo de la API.

Solución de problemas

• details viene null: pasa en errores genéricos (401, 403, 404, 500) que no tienen información estructurada adicional; el message es la única pista.
• Recibo un código HTTP que no está en la tabla: para status no mapeados, code se calcula como status * 100 (ej: un 418 devolvería 41800).