Errores del navegador (SDK y widget)

Con este endpoint el SDK, el widget o tu propia interfaz envían en lotes los errores que se producen en el navegador del usuario. Así puedes detectar fallos de tu integración sin esperar a que alguien los cuente, y verlos en la pestaña Errores de tu aplicación (lo explica Pestaña de errores de la aplicación).

El SDK de JavaScript y el widget los envían solos. Si construyes tu propia integración, puedes llamar a este endpoint directamente.

Plan y permisos

Hace falta el aplicativo Integraciones en el plan de tu organización y el permiso analytics:errors:write en la aplicación. El endpoint admite 30 peticiones por minuto por aplicación.

Enviar errores

Cabeceras

X-Api-Keystringobligatorio

Clave de API externa (formato: utl_xxx)

Content-Typestringobligatorio

application/json

x-request-idstring

Identificador único para seguir la petición

Cuerpo de la petición

errorsClientErrorItemDto[]obligatorio

Lista de errores que envías (máximo 10 por petición)

Estructura de cada error (ClientErrorItemDto)

Respuesta correcta (201 Created)

receivednumber

Número de errores recibidos en la petición (el tamaño de la lista enviada)

El código es 201, no 200: acepta cualquier 2xx. Cada error se guarda sin hacer esperar a la respuesta, así que received confirma que ha llegado el lote, no que cada error se haya guardado ya.

Errores

Ejemplos

curl -X POST 'https://os.utilia.ai/api/external/v1/tickets/client-errors' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: utl_tu_clave_de_api' \
  -H 'x-request-id: req-errors-001' \
  -d '{
    "errors": [
      {
        "message": "Error al cargar la lista de tickets: timeout de red",
        "code": "NETWORK_TIMEOUT",
        "severity": "high",
        "endpoint": "/api/external/v1/tickets",
        "method": "GET",
        "requestId": "req-listar-tickets-042",
        "component": "TicketList",
        "url": "https://mi-app.com/soporte",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0"
      },
      {
        "message": "Error al parsear respuesta JSON del servidor",
        "stack": "SyntaxError: Unexpected token < in JSON at position 0\n    at JSON.parse (<anonymous>)\n    at processResponse (sdk.js:142:21)",
        "code": "PARSE_ERROR",
        "severity": "medium",
        "endpoint": "/api/external/v1/tickets/ai-suggest",
        "method": "POST",
        "component": "AiSuggestForm"
      }
    ]
  }'

Si usas el SDK oficial de JavaScript (@utilia-os/sdk-js), el envío es automático: solo necesitas este endpoint si construyes tu integración sin el SDK.

Buenas prácticas

Qué incluir en cada error

Cuanto más contexto, más fácil el diagnóstico:

• requestId: si el error ocurrió durante una petición a la API y le diste un x-request-id, pon ese mismo valor para cruzarlo con los registros del servidor.
• component: el componente de la interfaz donde ocurrió. Nombres claros como TicketForm, ChatWidget o FileUpload ayudan a localizarlo.
• severity: clasifícalo bien. Reserva critical para errores que impiden del todo usar la función.

Cómo enviarlos

Como el máximo son 10 errores por petición, guárdalos en una cola local y envíalos en lotes: en cuanto la cola llegue a 10 o, si no, cada 30 segundos.

Niveles de gravedad

Siguiente paso

Revisa los errores recibidos en la pestaña Errores de tu aplicación o consúltalos por la API con los endpoints de errores de tu aplicación.