Errores de tu aplicación

Con estos endpoints tu aplicación informa a UTILIA OS de los errores de su servidor, y luego los lista y consulta sus estadísticas. Cada error queda asociado a la aplicación que lo envía; los repetidos se agrupan en uno solo con un contador. Los ves también en la pestaña Errores de la aplicación.

Autenticación, plan y permisos

Todas las peticiones llevan la cabecera X-Api-Key. El plan de tu organización tiene que incluir el aplicativo Integraciones.

Sin el permiso, los endpoints responden 403 INSUFFICIENT_SCOPE con un mensaje genérico que pide hablar con el administrador de la organización. Se exige desde la primera llamada, sin periodo de gracia. El catálogo completo y las reglas de concesión están en Permisos de la API.

Informar de un error

Cuerpo

Si pones el código HTTP del fallo en context.httpStatus, context.statusCode o context.errorCode, UTILIA OS lo usa para clasificarlo: los 4xx (errores de negocio esperados) se descartan sin registrarlos, y los 408, 502, 503 y 504 (cortes pasajeros) se registran con gravedad low. En los dos casos la respuesta es correcta.

Respuesta

{
  "success": true,
  "hash": "a1b2c3d4e5f6...",
  "deduplicated": false
}

• hash: identificador del error. Agrupa todas las veces que se repite el mismo error. Viene vacío si el error se ha descartado.
• deduplicated: true si el error ya existía y solo ha subido su contador.

Ejemplos

curl -X POST 'https://os.utilia.ai/api/external/v1/errors/report' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: utl_xxx' \
  -d '{
    "message": "Connection timeout to payment gateway",
    "module": "payment-processor",
    "severity": "critical",
    "stack": "Error: Connection timeout\n    at PaymentGateway.charge (/app/src/payments.ts:45)",
    "endpoint": "/api/payments/charge",
    "method": "POST",
    "context": {
      "gatewayId": "stripe",
      "orderId": "order-456"
    }
  }'

Listar los errores

Parámetros de consulta

severitystring[]

Filtra por gravedad: critical, high, medium o low (admite varias)

modulestring

Filtra por módulo de origen

resolvedboolean

Filtra por si están resueltos o no

limitnumber

Número de resultados (de 1 a 200, por defecto 50)

offsetnumber

Cuántos resultados saltar, para paginar

fromstring

Fecha ISO de inicio, sobre la última vez que ocurrió

tostring

Fecha ISO de fin, sobre la última vez que ocurrió

Respuesta

{
  "errors": [
    {
      "id": "err_1",
      "hash": "a1b2c3d4e5f6...",
      "message": "Connection timeout to payment gateway",
      "module": "payment-processor",
      "severity": "critical",
      "file": "/app/src/payments.ts",
      "line": 45,
      "endpoint": "/api/payments/charge",
      "count": 12,
      "firstOccurrence": "2026-02-25T10:00:00.000Z",
      "lastOccurrence": "2026-02-27T14:30:00.000Z",
      "resolved": false,
      "resolvedAt": null
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

Ejemplos

curl 'https://os.utilia.ai/api/external/v1/errors?severity=critical&severity=high&resolved=false&limit=20' \
  -H 'X-Api-Key: utl_xxx'

Estadísticas de errores

Respuesta

{
  "total": 156,
  "unresolved": 42,
  "bySeverity": {
    "critical": 5,
    "high": 18,
    "medium": 12,
    "low": 7
  },
  "byModule": {
    "payment-processor": 15,
    "auth": 8,
    "api-gateway": 19
  },
  "topErrors": [
    {
      "hash": "a1b2c3d4e5f6...",
      "message": "Connection timeout to payment gateway",
      "count": 34,
      "severity": "critical"
    }
  ]
}

• topErrors: los 10 errores sin resolver que más se repiten.

Ejemplos

curl 'https://os.utilia.ai/api/external/v1/errors/stats' \
  -H 'X-Api-Key: utl_xxx'

Errores frecuentes

• 400: cuerpo no válido (message o module vacíos, severity no admitida).
• 401: falta la clave de API, no es válida o no es de una aplicación externa.
• 403: falta el permiso analytics:errors:*, la aplicación está desactivada, el origen no está permitido (CORS) o el plan no incluye Integraciones.
• 429: se ha superado el límite por hora de la clave. La respuesta trae la cabecera Retry-After.

Envía x-request-id en cada petición para poder seguirla en los registros.

Siguiente paso

Para los errores que se producen en el navegador de tus usuarios (SDK, widget o tu propia interfaz) usa Errores del navegador. Para revisarlos, resolverlos o convertirlos en ticket, abre la pestaña Errores de la aplicación.