# Pestaña de errores de la aplicación Qué hace tu equipo, desde la ficha de la aplicación en UTILIA OS, con los errores que envía tu integración, y qué avisos recibe tu servidor por cada acción. Los errores que envía tu aplicación, con `install` y `capture` del SDK, con `POST /external/v1/errors/report` o `/batch`, o los fallos del widget por `POST /external/v1/tickets/client-errors`, llegan agrupados a **Actividad › Errores**, en la ficha de la aplicación, en [Ajustes › Creadas por tu empresa](https://os.utilia.ai/dashboard/settings/custom-apps). Desde ahí tu equipo los investiga, los silencia, los resuelve, los reabre o los convierte en un ticket de soporte o en un elemento de trabajo de Gestión de proyectos. Esta página explica lo que pasa en ese lado, para que sepas qué avisos recibirá tu servidor y cómo encaja todo el circuito de soporte. > **Nota: Quién usa esta pestaña** > > Es una pantalla de UTILIA OS para las personas de tu organización, no algo que tu aplicación muestre a sus usuarios. Verla exige el permiso **Ver los errores de las aplicaciones externas** (`EXTERNAL_APPS_ERRORS_VIEW`) y actuar sobre los errores, **Gestionar los errores de las aplicaciones externas** (`EXTERNAL_APPS_ERRORS_MANAGE`). Tu aplicación puede hacer lo mismo por la API con `analytics:errors:manage` ([Consultar y gestionar los errores](https://os.utilia.ai/docs/developers/api/errors-manage)). ## Qué muestra - **Estado general**: una frase en lenguaje claro y un semáforo (`ok`, `warning`, `danger`) calculado con los errores pendientes. Por ejemplo: «3 errores críticos activos sin resolver». - **Cifras clave**: errores sin resolver, críticos activos, veces que han ocurrido en las últimas 24 horas y variación frente al día anterior, más una tasa de error. - **Últimas 24 horas**: un gráfico de barras con un punto por hora, para ver los picos. - **Lista de grupos**: un grupo por error, con gravedad, módulo, número de veces, primera y última vez, estado y enlaces al ticket o al elemento de trabajo si existen. Si enviaste `release`, marca «Nuevo en 2.4.1»; si un error resuelto ha vuelto, «Ha vuelto una vez» o «Ha vuelto 3 veces». ## Estados de un grupo de errores El estado no se guarda: se calcula cada vez que se consulta, a partir de si está resuelto y de si tiene un silencio vigente. **Estados de un grupo de errores** 1. **Activo** (`active`). Cuenta en las cifras y dispara las alertas. - **Silenciado** (`silenced`). Se llega desde Activo cuando: Se silencia de 1 a 672 horas. Sigue sumando veces, pero no cuenta como pendiente ni avisa. 2. **Resuelto** (`resolved`). Se llega desde Activo cuando: Se resuelve o se cierra lo vinculado. Sale de la lista por defecto. Si vuelve a ocurrir, se reabre solo. Otras transiciones: - Resuelto → Activo: Vuelve a ocurrir (regresión) o alguien pulsa «Reabrir». - Silenciado → Activo: Vence el plazo, o alguien quita el silencio. **Un error resuelto que vuelve a ocurrir se reabre solo.** El grupo pasa a activo, suma una regresión (`regressionCount`), tu servidor recibe `ERROR_REOPENED` con `reason: regression` y, si el error es crítico o de gravedad alta, tu equipo recibe un aviso. Así nadie da por arreglado algo que sigue fallando. ## Gravedad y semáforo La gravedad que envía tu aplicación (`critical`, `high`, `medium`, `low`) decide el color del estado general: - **danger**: hay al menos un error `critical` activo. - **warning**: hay un pico (en las últimas 24 horas, el doble o más que el día anterior) o errores activos, ninguno crítico. - **ok**: ningún error activo. Un grupo guarda la gravedad más alta que ha visto: si el mismo fallo llega una vez como `high` y otra como `critical`, el grupo queda en `critical`. ## Qué puede hacer tu equipo ### Silenciar Oculta un grupo de las cifras y las alertas de 1 hora a 4 semanas, por ejemplo mientras se investiga. Volver a silenciarlo sustituye el plazo anterior, y poner 0 horas quita el silencio antes de tiempo. Aviso a tu servidor: `ERROR_SILENCED`, con `until` (fecha ISO 8601) o `null` si se quita el silencio. ### Resolver Cierra el grupo, con una nota interna opcional de hasta 2.000 caracteres sobre la causa o la solución. Resolver uno ya resuelto no cambia nada ni repite el aviso. Aviso: `ERROR_RESOLVED`, con `resolvedBy` y `note`. También se resuelve solo cuando se cierra lo que tiene vinculado: el ticket de soporte pasa a resuelto o cerrado, o el elemento de trabajo, a hecho o cancelado. Si después el error vuelve a ocurrir, el grupo se reabre, pero el ticket o la tarea no: decidir si ese trabajo vuelve a empezar es de una persona. ### Reabrir Devuelve un grupo resuelto a activo, por ejemplo si la corrección no funcionó. Aviso: `ERROR_REOPENED`, con `reason: manual` y `reopenedBy`. ### Crear un ticket de soporte Crea un ticket de categoría `BUG` a partir del grupo, con la descripción ya rellena (mensaje, módulo, identificador del grupo y ruta). Tu equipo puede cambiar el título, la descripción y la prioridad antes de crearlo. El grupo queda enlazado al ticket y la lista muestra su clave (por ejemplo, `mi-app-0001`). Aviso: `ERROR_LINKED_TO_TICKET`, con el ticket en `ticket` (`id` y `ticketKey`). ### Crear un elemento de trabajo Crea un elemento de trabajo en Gestión de proyectos (tipo `BUG` si la gravedad es alta o crítica; `TASK` en otro caso) en el proyecto vinculado a la aplicación. Si la aplicación no tiene proyecto vinculado, hay que elegirlo al crearlo. El grupo queda enlazado y la lista muestra su clave (por ejemplo, `PROJ-123`). Aviso: `ERROR_LINKED_TO_ISSUE`, con el elemento en `issue` (`id` y `key`). Mientras un grupo siga sin resolver con un ticket o una tarea vinculados, no caduca: el resto se borra a los 14 días de su última ocurrencia. ### Varios grupos a la vez Tu equipo puede seleccionar varios grupos y resolverlos, reabrirlos o silenciarlos de una vez (hasta 100 por operación). Cada grupo se procesa por separado: si uno falla, los demás siguen. ## Avisos que recibe tu servidor Tu aplicación puede recibir seis eventos de errores. El contenido de cada uno está en [Contenido de los avisos](https://os.utilia.ai/docs/developers/webhooks/events#errores-del-sistema): - `ERROR_REPORTED`: tu aplicación ha enviado un error nuevo, con `count`, `release` y `environment`. No se repite cuando un error ya conocido vuelve a ocurrir y solo sube su contador. - `ERROR_RESOLVED`: alguien ha resuelto un grupo, desde esta pestaña, por la API o al cerrar lo vinculado. - `ERROR_REOPENED`: un grupo resuelto se ha reabierto, a mano (`reason: manual`) o porque volvió a ocurrir (`reason: regression`). - `ERROR_SILENCED`: un grupo se ha silenciado o se le ha quitado el silencio. - `ERROR_LINKED_TO_TICKET`: se ha creado y enlazado un ticket de soporte. - `ERROR_LINKED_TO_ISSUE`: se ha creado y enlazado un elemento de trabajo. Todos se firman y se reintentan igual que el resto de avisos: [Firma HMAC](https://os.utilia.ai/docs/developers/webhooks/hmac-signature) y [Entregas y reintentos](https://os.utilia.ai/docs/developers/webhooks/delivery-and-retries). Solo llegan los eventos a los que suscribas la aplicación en su sección **Avisos a tu servidor**. ## Buenas prácticas para tu aplicación Lo que envíes decide lo útil que le resultará a tu equipo: - **Deja que se agrupe solo, o dile cómo.** Dos errores son el mismo cuando coinciden el módulo, el mensaje y el primer marco de la pila que es de tu código. Los identificadores largos, las fechas, los correos y las IP del mensaje ya se cambian por un comodín, pero los textos entre comillas y los números cortos no: si tu mensaje los lleva y cambian en cada ocurrencia, quítalos o agrupa con `fingerprint` ([Agrupación propia](https://os.utilia.ai/docs/developers/sdk/error-reporting#agrupación-propia)). - **Envía `release`.** La lista marca qué errores son nuevos en cada versión, y una regresión dice en qué versión volvió el fallo. - **Usa `severity` con criterio.** Un error `critical` nuevo pone el estado en rojo y avisa, en la aplicación y por correo según las preferencias de cada uno, a quienes pueden ver los errores, empezando por la persona responsable de la aplicación. Resérvalo para incidentes que afectan al servicio. - **Aprovecha `context`.** Lo que mandes ahí aparece en el detalle del error, después de quitarle correos, tokens y credenciales. Es la mejor pista para diagnosticar. - **Escucha `ERROR_RESOLVED` y `ERROR_REOPENED`.** Si tu aplicación cierra sus alertas internas cuando tu equipo resuelve el error y las reabre con una regresión, nadie atiende alertas viejas ni se pierde una vuelta. ## Siguiente paso - [Capturar los errores de tu aplicación](https://os.utilia.ai/docs/developers/sdk/error-reporting): install y capture con los SDK: la integración en dos líneas. - [Consultar y gestionar los errores](https://os.utilia.ai/docs/developers/api/errors-manage): Lo mismo que hace tu equipo en esta pestaña, desde tu código.