Consultar y gestionar los errores

Tu aplicación puede leer los errores que ella misma ha enviado y gestionarlos igual que tu equipo en la pestaña Errores: resolverlos cuando sale la corrección, reabrirlos o silenciarlos durante un incidente que ya conoces. Solo ve los suyos, nunca los de otra aplicación ni los internos de UTILIA OS, y cada cambio avisa a tu servidor. Cómo se envían está en Enviar los errores de tu aplicación.

Autenticación y permisos

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

Las cuatro rutas de gestión actúan en nombre de la persona responsable de la aplicación. Esa persona necesita además el permiso Gestionar los errores de las aplicaciones externas, el mismo que pide la pestaña Errores: por la API no se puede hacer más que en el panel. Cada acción queda en el registro de auditoría a su nombre.

Como el envío, estas rutas admiten 120 peticiones por minuto cada una, por aplicación. A diferencia del envío, sí cuentan en el cupo por hora de tu clave, como cualquier otra petición de la API.

Listar los errores

Parámetros de consulta

Los grupos salen de más a menos graves y, dentro de cada gravedad, del más reciente al más antiguo.

Respuesta

{
  "data": [
    {
      "id": "cm9x2k1ab0001",
      "hash": "5f2b7c1e9a0d4e3b8c6a1f7d2e9b0c4a",
      "message": "Tiempo de espera agotado con la pasarela",
      "module": "pagos",
      "severity": "critical",
      "file": "src/pagos.ts",
      "line": 45,
      "endpoint": "/api/pagos/cobrar",
      "count": 37,
      "firstOccurrence": "2026-10-20T09:12:00.000Z",
      "lastOccurrence": "2026-10-22T08:41:00.000Z",
      "resolved": false,
      "resolvedAt": null,
      "status": "active",
      "silencedUntil": null,
      "environment": "production",
      "firstRelease": "2.4.0",
      "lastRelease": "2.4.2",
      "regressionCount": 1,
      "lastRegressedAt": "2026-10-22T08:41:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

statusstring

active (sin resolver y sin silencio vigente), resolved o silenced.

silencedUntilstring | null

Hasta cuándo está silenciado, si lo está.

environmentstring | null

Entorno declarado al enviarlo. El entorno no separa grupos: si el mismo fallo llega de varios, queda el primero.

firstRelease, lastReleasestring | null

Primera y última versión en que se vio.

regressionCountnumber

Veces que ha vuelto a ocurrir después de darse por resuelto.

lastRegressedAtstring | null

Última vez que volvió tras darse por resuelto.

paginationobject

page (offset / limit + 1), limit, total y totalPages.

Ejemplos

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

En Python, from y to se escriben from_date y to_date, porque from es palabra reservada, y firstRelease, first_release.

Estadísticas

{
  "total": 156,
  "unresolved": 42,
  "silenced": 3,
  "bySeverity": { "critical": 5, "high": 18, "medium": 12, "low": 7 },
  "byModule": { "pagos": 15, "auth": 8, "importador": 19 },
  "topErrors": [
    {
      "hash": "5f2b7c1e9a0d4e3b8c6a1f7d2e9b0c4a",
      "message": "Tiempo de espera agotado con la pasarela",
      "count": 37,
      "severity": "critical"
    }
  ]
}

• total: grupos de la aplicación, en cualquier estado.
• unresolved: los pendientes, sin resolver y sin silencio vigente. Es la misma cifra que la pestaña Errores.
• silenced: los que están sin resolver con un silencio vigente.
• bySeverity y byModule: los pendientes, por gravedad y por módulo.
• topErrors: los diez pendientes con más ocurrencias, con el mensaje recortado a 100 caracteres.

Con los SDK, sdk.errors.stats().

Detalle de un error

Devuelve los campos del listado y, además:

{
  "hash": "5f2b7c1e9a0d4e3b8c6a1f7d2e9b0c4a",
  "status": "active",
  "stack": "Error: Tiempo de espera agotado\n    at cobrar (src/pagos.ts:45:12)",
  "function": "cobrar",
  "method": "POST",
  "context": {
    "pedidoId": "ped_456",
    "tags": { "pasarela": "redsys" },
    "externalUserRef": "usr-4821"
  },
  "resolutionNote": null,
  "lastRequestId": "req-pagos-0042",
  "linkedTicket": { "id": "tkt_123", "key": "SUP-482" },
  "linkedIssue": null
}

• stack y context llegan saneados, sin credenciales ni correos. El contexto es el de la última ocurrencia; las etiquetas están en context.tags y el userId que enviaste, en context.externalUserRef.
• lastRequestId: el identificador de petición de la última ocurrencia que lo traía.
• linkedTicket y linkedIssue: el ticket de soporte o la tarea de Gestión de proyectos vinculados, con su clave visible, o null.

Un hash que no existe, que es de otra aplicación o que no es tuyo responde el mismo 404. Con los SDK, sdk.errors.get(hash).

Resolver, reabrir y silenciar

Las cuatro acciones cambian el estado del grupo igual que los botones de la pestaña Errores, y cada una avisa a tu servidor. Los estados y qué los cambia están en Estados de un grupo de errores. Responden 200.

Resolver

note es opcional, de hasta 1.000 caracteres. La respuesta es { "hash": "…", "resolved": true, "alreadyResolved": false } y tu servidor recibe ERROR_RESOLVED. Si ya estaba resuelto, alreadyResolved: true: no cambia nada ni sale ningún aviso.

Si el error vuelve a ocurrir, se reabre solo: esa ocurrencia responde status: regressed, el grupo suma una en regressionCount y tu servidor recibe ERROR_REOPENED con reason: regression y la versión en release.

Reabrir

Sin cuerpo. La respuesta es { "hash": "…", "alreadyOpen": false } y tu servidor recibe ERROR_REOPENED con reason: manual. Si ya estaba abierto, alreadyOpen: true y no sale ningún aviso.

Silenciar y quitar el silencio

hours es obligatorio, un entero de 1 a 672 (cuatro semanas). Mientras dure, el grupo sigue sumando ocurrencias, pero no cuenta como pendiente ni avisa. Volver a silenciarlo sustituye el plazo. La respuesta trae el fin del silencio en silencedUntil y tu servidor recibe ERROR_SILENCED con esa fecha en until.

La respuesta es { "hash": "…", "silencedUntil": null }; si el grupo no está resuelto, vuelve a contar como pendiente. Tu servidor recibe ERROR_SILENCED con until: null.

Ejemplos

HASH=5f2b7c1e9a0d4e3b8c6a1f7d2e9b0c4a
 
curl -X POST "https://os.utilia.ai/api/external/v1/errors/$HASH/resolve" \
  -H 'Content-Type: application/json' -H 'X-Api-Key: utl_xxx' \
  -d '{ "note": "Corregido en la 2.4.2" }'
 
curl -X POST "https://os.utilia.ai/api/external/v1/errors/$HASH/silence" \
  -H 'Content-Type: application/json' -H 'X-Api-Key: utl_xxx' \
  -d '{ "hours": 24 }'
 
curl -X DELETE "https://os.utilia.ai/api/external/v1/errors/$HASH/silence" \
  -H 'X-Api-Key: utl_xxx'

Errores

APP_RESPONSIBLE_PERMISSION_DENIED no se arregla en los permisos de la aplicación, sino en los de su persona responsable.

Siguiente paso

• Pestaña de errores de la aplicaciónLos estados de un grupo y lo que tu equipo hace con él desde el panel.
• Contenido de los avisosLos campos de ERROR_RESOLVED, ERROR_REOPENED y ERROR_SILENCED.