Manejo de errores

Cuando una llamada a la API falla (respuesta HTTP 4xx o 5xx), el SDK lanza una instancia de tipo FactusError. Esta clase extiende Error nativo de JavaScript y añade información estructurada del error devuelto por la API.

La clase `FactusError`

class FactusError extends Error {
  name: "FactusError";
  statusCode: number;
  errors: Array<{
    code: number;
    message: string;
    detail: string;
    api_version: string;
  }>;
  validationErrors: Record<string, string> | null;
  cause?: unknown;
}

Prop

Type

Importar `FactusError`

import { FactusError } from "factus-js";

Ejemplo básico

import { FactusClient, FactusError } from "factus-js";

const factus = new FactusClient({
  /* config */
});

try {
  const invoice = await factus.bills.get("NO-EXISTE");
} catch (error) {
  if (error instanceof FactusError) {
    console.error("Error de la API:", error.message);
    console.error("Código HTTP:", error.statusCode);
    console.error("Errores detallados:", error.errors);
  } else {
    // Error de red u otro error inesperado
    throw error;
  }
}

Errores de validación

Cuando la API rechaza un documento por reglas de validación (HTTP 422), el SDK extrae los errores DIAN y los expone directamente en error.validationErrors:

try {
  const invoice = await factus.bills.create({
    /* datos de factura */
  });
} catch (error) {
  if (error instanceof FactusError) {
    console.error("Código HTTP:", error.statusCode); // 422

    if (error.validationErrors) {
      // Errores de validación de la DIAN — { [código]: descripción }
      for (const [code, detail] of Object.entries(error.validationErrors)) {
        console.error(`${code}: ${detail}`);
        // "FAK24: Regla: FAK24, Rechazo: No está informado el DV del NIT"
      }
    }
  }
}

La respuesta raw de la API para estos casos tiene la siguiente forma:

{
  "status": "Validation error",
  "message": "El documento contiene errores de validación",
  "data": {
    "message": "El documento contiene errores de validación",
    "errors": {
      "FAK24": "Regla: FAK24, Rechazo: No está informado el DV del NIT"
    }
  }
}

Errores comunes

Código HTTP	Situación típica
`400`	Datos de entrada inválidos o campo requerido faltante
`401`	Credenciales inválidas o token expirado
`403`	Sin permisos para realizar la operación
`404`	Recurso no encontrado (ID incorrecto)
`422`	Error de validación de la DIAN (campos del documento)
`429`	Límite de solicitudes superado
`500`	Error interno del servidor de Factus

Errores de red

Las llamadas de red que fallen antes de llegar al servidor (sin conexión, DNS, timeout) lanzarán el error nativo del fetch API, no un FactusError. Comprueba siempre instanceof FactusError antes de acceder a las propiedades adicionales.