Notificar errores de tu aplicación

El servicio errors sirve para que tu aplicación envíe sus propios errores a UTILIA OS y los consulte después. En tu organización, quien tenga permiso los ve agrupados en la pestaña de errores de la aplicación. Funciona con la clave de tu aplicación externa, siempre desde tu servidor.

No lo confundas con UtiliaSDKError, que es el error que lanza el SDK cuando una llamada falla.

Antes de empezar

Los listados y las estadísticas solo incluyen los errores que ha notificado tu propia aplicación.

Notificar un error

Solo dos campos son obligatorios: message (hasta 2000 caracteres) y module, el área de tu aplicación donde ocurrió (hasta 100). El resto aporta contexto para depurar:

try {
  await procesarPago(orden);
} catch (error) {
  const result = await sdk.errors.report({
    message: error instanceof Error ? error.message : String(error),
    module: 'pagos',
    severity: 'critical',
    stack: error instanceof Error ? error.stack : undefined,
    endpoint: '/api/payments',
    method: 'POST',
    userId: 'usr-789',
    context: { ordenId: orden.id, pasarela: 'stripe' },
  });
  console.log(result.hash, result.deduplicated);
}

La respuesta trae success, hash (la huella que agrupa los errores iguales) y deduplicated, que vale true si ese error ya existía y solo se ha sumado una ocurrencia. Gracias a esa agrupación no necesitas filtrar los duplicados en tu lado.

Consultar errores y estadísticas

Filtros de list, todos opcionales: severity (lista de severidades), module, resolved, limit (50 por defecto, 200 como máximo), offset para paginar, y un rango de fechas ISO 8601 con from y to (en Python, from_date y to_date, porque from es palabra reservada). Cada error trae su hash, message, module, severity, count de ocurrencias, la primera y la última ocurrencia, y si está resuelto.

stats devuelve el total, los no resueltos, el reparto por severidad y por módulo, y los errores más frecuentes (topErrors, top_errors).

const result = await sdk.errors.list({
  severity: ['critical', 'high'],
  resolved: false,
  from: '2026-09-01T00:00:00Z',
  limit: 20,
});
for (const item of result.data) {
  console.log(`[${item.severity}] ${item.message} (x${item.count})`);
}
 
const stats = await sdk.errors.stats();
console.log(`${stats.unresolved} de ${stats.total} sin resolver`);

Capturar los errores no controlados

Un patrón habitual en un proceso de servidor es notificar lo que se escapa de cualquier bloque de captura. Hazlo en tu servidor, donde vive la clave: no en el navegador.

process.on('unhandledRejection', (reason) => {
  void sdk.errors.report({
    message: String(reason),
    module: 'servidor',
    severity: 'medium',
    context: { tipo: 'promesa-rechazada-sin-capturar' },
  });
});

Siguiente paso

• Pestaña de errores de la integraciónQué ve tu organización de los errores que notificas y qué puede hacer con ellos.
• Endpoints de errores de tu aplicaciónLas mismas operaciones desde la API REST.