Guía definitiva sobre errores de WebAuthn en producción (2026)

En producción, los errores de WebAuthn son confusos porque los navegadores exponen un pequeño conjunto de nombres de DOMException (como NotAllowedError) que pueden representar múltiples causas subyacentes. Además, la gran mayoría de los "errores" (a menudo por encima del 95 % en implementaciones optimizadas a gran escala) son en realidad comportamiento esperado (el usuario canceló el mensaje de clave de acceso del sistema operativo).

Experimenta con flujos de passkeys en Passkeys Debugger.

Probar gratis

Si desea las definiciones canónicas para estos nombres, comience con DOMException en MDN. Para las condiciones específicas de WebAuthn que conducen a estas excepciones (y lo que los navegadores están obligados a aplicar), consulte la especificación de Web Authentication del W3C.

Si trata todos los errores como "errores del sistema", hará las cosas mal:

• Contaminará sus métricas de errores con cancelaciones normales.
• Pasará por alto regresiones reales ocultas dentro de la masa de NotAllowedError.
• Enviará una interfaz de usuario que confunde a los usuarios en lugar de ayudarles a recuperarse.

En este artículo respondemos a lo siguiente:

• ¿Qué significan normalmente los nombres de error más comunes de WebAuthn en el tráfico real?
• ¿Cómo se desambigua NotAllowedError en grupos procesables (cancelación vs. tiempo de espera vs. disponibilidad)?
• ¿Por qué el mismo error significa cosas diferentes según la operación (inicio de sesión de interfaz de usuario condicional vs. inicio de sesión modal vs. creación de claves de acceso vs. creación condicional)?
• ¿Qué contexto mínimo debe capturar para que "falló" se convierta en un problema reproducible?

Si solo necesita una asignación rápida para desbloquear la depuración, comience con esta tabla. Está sesgada hacia lo que los equipos realmente ven en los paneles y en los tickets de soporte.

Una cosa que es fácil pasar por alto: el mismo error.name puede significar cosas muy diferentes dependiendo del tipo de operación. Tenga en cuenta el contexto de la operación al leer las siguientes secciones. En la práctica, los errores de creación de claves de acceso (registro) generalmente superan en número a los errores de inicio de sesión por un amplio margen: la tabla anterior se aplica a ambos, pero la creación es donde reside la mayor parte del volumen.

A continuación, profundizaremos en NotAllowedError porque es el que verá con más frecuencia y el que los equipos interpretan mal con mayor frecuencia.

NotAllowedError a menudo parece "fallaron las claves de acceso", pero normalmente es la plataforma diciéndole que el usuario no completó la interfaz de usuario del sistema operativo. La clave es dividirlo en grupos sobre los que pueda actuar.

Lo que verá en la consola del navegador:

Todos estos se manifiestan como error.name === "NotAllowedError". El error.message difiere según el motor del navegador y la causa subyacente, pero el resultado es el mismo: la ceremonia no se completó.

Esto se aplica tanto al inicio de sesión como a la creación de claves de acceso. Durante el inicio de sesión (interfaz de usuario condicional, modal con o sin lista de permitidos), NotAllowedError suele significar que el usuario no completó la ceremonia. Durante la creación de claves de acceso, el mismo error surge por diferentes razones: el usuario descartó el cuadro de diálogo de creación (la creación condicional no funcionó, o la página perdió el foco durante una adición activada automáticamente). El tipo de operación cambia lo que significa el error y lo que debe hacer al respecto.

El tiempo a menudo es una señal subestimada. Un error después de menos de un segundo de un clic suele ser un rechazo inmediato (el entorno no puede hacerlo, el documento no está enfocado, falta de capacidad). Un error después de unos segundos es una cancelación del usuario (vieron el cuadro de diálogo y decidieron no continuar). Un error después de 30 o más segundos es un tiempo de espera. En las plataformas nativas, el tiempo es especialmente importante: los viajes de ida y vuelta del autenticador, las indicaciones biométricas y las transferencias del administrador de credenciales tienen duraciones características que le ayudan a separar "no funcionó" de "el usuario se alejó". Aún así, no puede distinguir fácilmente si existía una clave de acceso.

No necesita una señal perfecta. Necesita suficiente contexto para evitar tratar cada NotAllowedError de la misma manera. A iOS/Safari se le presta especial atención a continuación porque tiene restricciones únicas (requisitos de activación del usuario en versiones anteriores), pero en el volumen de errores sin procesar, Windows y los navegadores Chromium a menudo generan más NotAllowedError que cualquier otra plataforma. Estas señales a menudo le llevan al 80 % del camino:

Esta es también la razón por la que NotAllowedError rara vez debería ser visible para el usuario. No es un mensaje sobre el que el usuario pueda actuar.

La clasificación por contexto es también donde las tasas de éxito se dividen más marcadamente. El análisis de la tasa de éxito de la autenticación de claves de acceso del Corbado Passkey Benchmark 2026 mide la finalización del primer trimestre de 2026 entre el 55 y el 95 % para los flujos centrados en el identificador en dispositivos desconocidos, frente al 95-99 % para los retornos en dispositivos conocidos en implementaciones B2C a gran escala. El primer identificador web de iOS alcanza el 85-95 % de finalización (% CDA 0-5 %), el web de Android el 70-85 % (% CDA 5-10 %) y el web de macOS el 70-85 % (% CDA 10-15 %), mientras que el web de Windows se sitúa en un 45-60 % de finalización del primer identificador con un % CDA en 55-65 % en Windows 11 y 40-55 % en Windows 10. Leer el volumen de NotAllowedError sin separar los contextos de dispositivos conocidos y desconocidos confunde dos regímenes de éxito fundamentalmente diferentes.

Un matiz que importa en producción: algunos agentes de usuario pueden mostrar los tiempos de espera como TimeoutError, pero muchos equipos todavía ven que los tiempos de espera se colapsan en NotAllowedError en los paneles. De cualquier manera, trate los tiempos de espera como "la ceremonia no se completó" y agrúpelos usando el tiempo más el contexto.

Cuando se descarta la hoja del sistema operativo o se agota el tiempo de espera, su interfaz de usuario debería recuperarse inmediatamente y reaccionar con gracia. Un conjunto práctico de reglas:

• Restaurar la interfaz de usuario de inicio de sesión (sin ruedas giratorias que sigan funcionando).
• Mantener el estado del identificador (no forzar el reingreso).
• Mostrar una alternativa visible en la misma pantalla.
• Evitar pancartas aterradoras para los resultados esperados.

Más allá de lo básico:

• Tratar la primera interrupción como normal y ofrecer un reintento con una explicación tranquila. Solo después de una segunda interrupción debería sugerir opciones alternativas.
• Permitir hasta tres solicitudes de creación antes de un tiempo de espera para que los usuarios sorprendidos tengan una segunda oportunidad.
• Dividir los recuentos de errores entre la creación y los inicios de sesión para comparar manzanas con manzanas.
• Segmentar las tasas de error por sistema operativo, navegador y dispositivo para que pueda detectar dónde reside realmente la fricción.

Si sus "cancelaciones" son realmente altas, el siguiente paso es solucionar las causas fundamentales subyacentes: tiempo de solicitud, sorpresas de códigos QR y baja disponibilidad.

Comience con los cambios que mueven las métricas rápidamente:

• Arreglar el tiempo de la solicitud y la activación del usuario (especialmente en iOS/Safari).
• Reducir las sorpresas de QR/híbrido.
• Limitar las ofertas para que las claves de acceso se muestren cuando es probable que tengan éxito.
• Usar patrones que eviten preguntar cuando no existe ninguna credencial local.
• Manejar la inestabilidad de la red: Los errores de red durante la verificación a menudo se manifiestan como fallos genéricos del lado del cliente. Implemente una cola fuera de línea para sus registros de telemetría para que no pierda los datos de error cuando la conexión del usuario se caiga durante la ceremonia.
• Limitar las ceremonias con API de detección para que los fallos del entorno no inflen su grupo de NotAllowedError. Comience con isUVPAA() como la puerta más básica, luego use getClientCapabilities() para comprobaciones más precisas (creación condicional, obtención condicional, transporte híbrido, autenticador de plataforma). Tenga en cuenta que las API de detección pueden romperse con las actualizaciones del sistema operativo: iOS 26.2 envió un error de WebKit donde isUVPAA() devuelve false en todos los navegadores basados en WKWebView a pesar de que las claves de acceso funcionan bien, causando picos repentinos de NotAllowedError para el 10-25 % de los usuarios de iOS.

Los nombres de error son un objetivo en movimiento. Hay propuestas en curso para agregar errores WebAuthn más granulares (por ejemplo, para separar "no hay credencial disponible" de "usuario cancelado"). A partir de febrero de 2026, esto no está implementado en ningún navegador, por lo que todavía vale la pena construir sus propios grupos de razones según el contexto y el tiempo. Si desea realizar un seguimiento de este trabajo, consulte el problema #2062 de WebAuthn y la explicación sobre los "Nuevos códigos de error".

Los nombres de error restantes son menos frecuentes pero aún vale la pena entenderlos cuando aparecen.

AbortError es poco común en volumen en comparación con NotAllowedError, pero cuando aparece es altamente diagnóstico: por lo general, significa que la ceremonia no terminó porque su aplicación invalidó la solicitud: ocurrió una navegación, cambió el estado o comenzó una segunda solicitud.

Lo que verá en la consola del navegador:

Las causas comunes de producción incluyen:

• Múltiples llamadas WebAuthn concurrentes (dos solicitudes compitiendo).
• Cambio de ruta/re-renderizado durante una ceremonia en curso.
• Llamar a AbortController.abort() durante reintentos o limpieza de estado.

Para solucionarlo, céntrese en hacer de la ceremonia una "sección crítica":

• Permitir solo una solicitud en curso a la vez.
• Bloquear la navegación durante la ceremonia (o cancelar limpiamente y restaurar la interfaz de usuario).
• Tratar la interrupción como un flujo de control esperado: mostrar un botón de reintento y un método alternativo.

Si ve que AbortError se concentra en superficies incrustadas o aplicaciones multidominio, el siguiente grupo que debe verificar es SecurityError.

SecurityError es el navegador diciéndole: "a este contexto no se le permite hacer lo que pidió". En la práctica es casi siempre de configuración, no comportamiento del usuario. En las implementaciones maduras de producción, SecurityError es raro porque estos problemas normalmente se detectan durante las pruebas de integración. Si aparece en producción, por lo general significa que se agregó un nuevo dominio, contexto de incrustación o destino de implementación sin la configuración adecuada de WebAuthn.

Las causas comunes incluyen:

• Falta de coincidencia del ID del RP/origen (configuraciones multidominio).
• Restricciones de incrustación de origen cruzado (iframes).
• Contexto inseguro (no HTTPS) o permisos/políticas bloqueados.
• .well-known/webauthn o .well-known/assetlinks.json mal configurados, faltantes o no disponibles temporalmente. Los problemas de red durante la ventana crítica cuando el navegador obtiene estos archivos causarán fallos. Un punto ciego común: si su página de inicio está inactiva por mantenimiento, los archivos "well-known" también están fuera de línea, rompiendo las ceremonias de claves de acceso en todas las partes que confían (relying parties) y que dependen de ellos.

Lo que verá en la consola del navegador:

En producción, SecurityError es raro: casi siempre se detectan durante las pruebas de integración. Cuando aparecen, el error en el certificado TLS es el sobreviviente más común.

El ciclo de depuración más rápido es:

• Registrar las entradas de origen y de ID de RP que utilizó.
• Reproducir en el mismo contexto (nivel superior vs. iframe, dominio de producción vs. staging).
• Si incrusta el inicio de sesión, confirme que la política de permisos está configurada (por ejemplo, publickey-credentials-create / publickey-credentials-get): Permissions-Policy de MDN.
• Verifique su estrategia de dominio.
• Si utiliza iframes, valide las políticas de características.

Una vez que se ha resuelto SecurityError, el siguiente grupo a tratar seriamente es el conjunto de errores que a menudo indican errores de implementación: InvalidStateError, ConstraintError y DataError.

Hoja de referencia de Passkeys. Guías prácticas, patrones de despliegue y KPIs para programas de passkeys.

Obtener cheat sheet

Estos errores deberían ser raros en una implementación de claves de acceso madura. Cuando aparecen, generalmente indican que la generación de opciones es incorrecta para un segmento o que el flujo está en un estado incorrecto.

Lo que verá en la consola del navegador:

Significados típicos:

• Registro: intentó crear una credencial que ya existe (duplicada).
• Inicio de sesión: menos común; a menudo significa que el flujo/estado es inconsistente para la plataforma.

Manejo práctico:

• Si ocurre en el registro manual, trátelo como "ya inscrito" y encamínelo en consecuencia.
• Asegúrese de que excludeCredentials enumera todos los identificadores de credenciales existentes para el usuario, de modo que el autenticador pueda detectar los duplicados.
• Durante la creación condicional, InvalidStateError es esperado y debe ser ignorado silenciosamente: significa que ya existe una clave de acceso en el proveedor. Lo mismo se aplica a NotAllowedError y AbortError durante la creación condicional (consulte creación condicional en Chrome).

Significado típico: el autenticador no puede satisfacer las restricciones solicitadas.

Desencadenantes comunes:

• Falta el bloqueo de pantalla del dispositivo (especialmente en Android): la plataforma requiere verificación biométrica o por PIN, pero el dispositivo no tiene configurada una pantalla de bloqueo.
• Suposiciones demasiado estrictas para authenticatorAttachment o la clave residente.
• Requisitos estrictos de userVerification en segmentos donde no están disponibles.

Arreglo: relaje las restricciones (cuando sea aceptable) o proporcione una ruta alternativa. Para el caso en el que falta el bloqueo de la pantalla, considere detectar esta condición y guiar a los usuarios en lugar de fallar silenciosamente (Android).

Significado típico: las entradas están mal formadas o son inconsistentes.

Desencadenantes comunes:

• Errores de codificación (base64 vs base64url).
• Identificadores de credenciales / formato de los desafíos no válidos.

Arreglo: valide y normalice las entradas en el límite donde genera las opciones de WebAuthn. En la práctica, DataError está efectivamente ausente en los sistemas de producción maduros: si su generación de opciones está probada, no lo verá en los paneles.

Si estos errores están bajo control, la siguiente pregunta es la cobertura: ¿están fallando los usuarios porque el entorno no puede hacer WebAuthn de la forma que usted espera?

NotSupportedError es una señal de cobertura, no una señal de fiabilidad. Suele significar que un segmento no puede hacer lo que usted pidió (sistema operativo/navegador demasiado antiguo, falta capacidad, característica no habilitada).

Lo que verá en la consola del navegador:

Los dos primeros son DOMException genuinos de tipo NotSupportedError. Las entradas TypeError son técnicamente un tipo de excepción diferente, pero representan la misma clase de problema: el navegador o el entorno no admiten lo que pidió. La familia de TypeError de serialización JSON es mucho más común en la práctica que el propio NotSupportedError DOMException (consulte a continuación).

Las causas comunes incluyen:

• Versiones más antiguas de navegadores/sistemas operativos que no admiten el WebAuthn básico.
• Solicitar características de WebAuthn no disponibles en esa plataforma.
• Intentar flujos específicos de la plataforma en dispositivos no compatibles.

La familia de serialización JSON es la mayor fuente de fallos de la clase NotSupportedError en producción. Técnicamente, estos aparecen como TypeError (falta el método), no como una DOMException, pero aquí es donde los encontrará. Dos causas subyacentes distintas:

1. El navegador no admite los métodos de serialización JSON de WebAuthn. El navegador tiene navigator.credentials pero no PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON. Esto representa aproximadamente el 90 % de esta familia de errores, concentrada en versiones antiguas de Safari y Chrome. Si su biblioteca de cliente depende de estos métodos sin una alternativa, esto produce un volumen de error significativo.
2. Las extensiones de administradores de contraseñas rompen .toJSON(). Las extensiones como Bitwarden, LastPass o 1Password pueden interceptar la ceremonia y devolver un objeto que parece una credencial pero no es una instancia real de PublicKeyCredential. Llamar a .toJSON() en ella lanza una excepción, devuelve un valor no definido, o el objeto es null por completo. Esto es aproximadamente el 10 % de la familia, pero es especialmente confuso para la depuración porque los mensajes de error difieren según el navegador (Safari: "Can only call on instances of PublicKeyCredential"; Firefox: "does not implement interface PublicKeyCredential").

El manejo debe ser contundente y rápido:

• Recurrir inmediatamente a la alternativa de contraseña/OTP.
• Registrar el segmento para que pueda cuantificar las lagunas de cobertura.
• Evitar mostrar llamadas a la acción (CTA) de claves de acceso en segmentos que fallarán sistemáticamente.

Si la cobertura parece estar bien pero los fallos siguen ocurriendo en segmentos específicos, es posible que se trate de problemas de la capa de plataforma expuestos como UnknownError.

UnknownError es un cajón de sastre para los fallos del autenticador/sistema operativo que no encajan claramente en las demás categorías. A menudo es transitorio, pero también puede tener picos después de las actualizaciones del sistema operativo.

Lo que verá en la consola del navegador:

Manejo práctico:

• Use UX compatible con reintentos (no "culpe al usuario").
• Capture las versiones del sistema operativo/compilación y el contexto del administrador/proveedor de credenciales cuando sea posible.
• Vigile los picos específicos de cada segmento después de las actualizaciones del sistema operativo.

Una fuente especializada de errores que no encaja claramente en ninguna categoría de DOMException: las extensiones de navegador de los administradores de contraseñas (como Bitwarden, LastPass, 1Password y otras) pueden interceptar las llamadas a la API de WebAuthn y devolver respuestas no estándar. Si bien el volumen es pequeño en comparación con las cancelaciones de los usuarios, vale la pena realizar un seguimiento porque afectan a segmentos de usuarios específicos de manera constante y los síntomas son confusos: faltan métodos en el objeto de credencial devuelto, tipos de error inesperados o respuestas mal formadas que no coinciden con ningún error documentado de WebAuthn. Estos a menudo surgen como UnknownError o como excepciones no clasificadas. Si ve picos de errores concentrados en navegadores específicos sin una explicación a nivel del sistema operativo, compruebe si hay implicada una extensión de un administrador de credenciales.

Hasta ahora hemos cubierto los nombres de errores en el navegador web. Pero si también envía aplicaciones nativas, el panorama de errores es diferente, y en cierto modo, significativamente mejor.

Todo lo anterior abarca los navegadores web. Las aplicaciones nativas (iOS con el framework ASAuthorization, Android con Credential Manager) comparten las mismas categorías de error fundamentales pero difieren de formas importantes:

1. "Sin credenciales" es una señal clara. En la web, los navegadores agrupan "no hay credencial disponible" y "el usuario canceló" en el mismo NotAllowedError por razones de privacidad. De forma nativa, usar preferImmediatelyAvailableCredentials en iOS (ASAuthorizationController) o setPreferImmediatelyAvailableCredentials(true) en Android (GetCredentialRequest) le indica al sistema operativo que solo presente las credenciales que ya se encuentran en el dispositivo y que falle inmediatamente si no existe ninguna. Esto le brinda una señal limpia de "no hay credenciales" que la web no puede proporcionar.

2. El estado del proveedor de credenciales es visible. Las plataformas nativas, bajo algunas condiciones, pueden decirle cuándo no hay ningún proveedor de credenciales (Google Password Manager, iCloud Keychain, 1Password, etc.) instalado, configurado o establecido como predeterminado y reaccionar ante ello. En la web, esta información está oculta detrás de mensajes opacos de NotAllowedError.

3. Los mensajes de error son más específicos. Debido a que el usuario ha instalado la aplicación, y por lo tanto, ha establecido una relación de confianza con la parte que confía (relying party), el sistema operativo muestra más detalles de diagnóstico. Las consideraciones de privacidad que obligan a los navegadores web a ser vagos no se aplican de la misma manera cuando la aplicación ya está en el dispositivo. iOS devuelve mensajes localizados en el idioma del dispositivo del usuario. Android devuelve tipos de error estructurados con cadenas de causa. Esto facilita la depuración, pero significa que su manejo de errores debe tener en cuenta la localización y los formatos de error específicos de la plataforma.

iOS muestra los errores de las claves de acceso a través del framework ASAuthorization. Todos los errores llegan en el callback de delegado authorizationController(controller:didCompleteWithError:) como objetos NSError.

Clasificar por dominio + código, no por la cadena de mensajes. El dominio de error primario es com.apple.AuthenticationServices.AuthorizationError (ASAuthorizationError.errorDomain). Transforme el error con let nsError = error as NSError y haga coincidir con .domain y .code. Nunca haga coincidir con .localizedDescription en producción: los mensajes de Apple están localizados en más de 30 idiomas y pueden cambiar en las distintas versiones del sistema operativo. Las cadenas de mensaje que se enumeran a continuación son útiles para reconocer los errores en los registros, pero no son criterios de clasificación.

Códigos públicos ASAuthorizationError:

La distinción más importante para la producción: desde iOS 18, las credenciales duplicadas devuelven su propio código de error 1006 (MatchedExcludedCredential). En iOS 17 y versiones anteriores, las credenciales duplicadas estaban ocultas dentro del código 1004 (Failed). En iOS 18+, la distinción es estructural (diferente código de error), no textual.

Errores comunes en tiempo de ejecución (referencia a nivel de registro):

Estos mensajes aparecen en localizedDescription o en userInfo para casos específicos de fallos. Úselos para búsquedas en los registros y la depuración, no para la clasificación programática.

Mensajes localizados de "sin credenciales" (código 1005):

Cuando se establece preferImmediatelyAvailableCredentials y no existe ninguna clave de acceso, iOS devuelve el código 1005 (NotInteractive) con un mensaje localizado en el idioma del dispositivo del usuario. Esto es exclusivo de las aplicaciones nativas: los navegadores web nunca exponen esta señal. El mensaje siempre comienza con The operation couldn't be completed. seguido por el texto localizado:

Los dispositivos con configuración regional en inglés (English-locale devices) por lo general resuelven el escenario "sin credenciales" en el nivel de API antes de que el framework ASAuthorization devuelva un error localizado, por lo cual no aparece ninguna variante en inglés en la lista anterior. Programáticamente, siempre verifique la coincidencia con el código 1005 en lugar de analizar gramaticalmente estas cadenas.

Android expone los errores de claves de acceso a través de la API Credential Manager (androidx.credentials). Los mensajes de error incluyen un mensaje primario y a menudo una causa (cause) con detalles adicionales. A diferencia de iOS, Android proporciona tipos de error más estructurados y causas más explícitas para los problemas de configuración.

Cancelación del usuario y detección de credenciales:

Errores de configuración y de seguridad:

Errores de la plataforma y del autenticador:

El siguiente diagrama muestra cómo todas las capas analizadas anteriormente (Infraestructura, Entorno, Tipo de operación, Clasificación y Detección) se conectan de un extremo a otro. Es el modelo mental que debe tener en cuenta al diseñar su seguimiento de errores.

flowchart TD
    %% Global Styles
    classDef expected fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef unexpected fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef network fill:#fff3e0,stroke:#ef6c00,stroke-dasharray: 5 5;
    classDef env fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px;
    classDef action fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;

    %% --- LEFT SIDE: NETWORK & SERVER ---
    subgraph Infrastructure ["Infraestructura (Servidor/Red)"]
        direction TB
        ServerErr["Error del lado del servidor<br/>500 / Error lógico"]:::network
        NetErr["Error de red<br/>Tiempo de espera / 400 Solicitud incorrecta"]:::network

        ServerErr & NetErr -->|Se manifiesta como| ClientManifest["Error genérico del lado del cliente"]
    end

    %% --- CENTER: THE ENVIRONMENT STACK (From Sketch) ---
    subgraph Environment ["El Entorno (Lado del cliente)"]
        direction TB

        %% Layer 1: Platform Type
        subgraph Type ["Capa 1: Plataforma"]
            Web["Web / Navegador"]
            Native["Nativo / Aplicación"]
        end

        %% Layer 2: OS Context
        subgraph OS_Layer ["Capa 2: SO y versión"]
            OS_Web["SO: Windows, macOS, Linux"]
            OS_Nat["SO: iOS, Android"]
            OS_Ver["Versión del SO / Ajustes<br/>(Bloqueo de pantalla, Biometría)"]

            Web --> OS_Web
            Native --> OS_Nat
            OS_Web & OS_Nat --> OS_Ver
        end

        %% Layer 3: Client Software
        subgraph Client_Layer ["Capa 3: Software del cliente"]
            Browser["Navegador: Chrome, Safari, Edge<br/>+ Versión"]
            App["Aplicación nativa / WebView<br/>+ Versión de la aplicación"]

            OS_Ver --> Browser
            OS_Ver --> App
        end

        %% Layer 4: WebAuthn Operation
        subgraph Op_Layer ["Capa 4: Operación WebAuthn"]
            OpType{"Tipo de operación"}

            Login["Inicio de sesión<br/>(navigator.credentials.get)"]
            Reg["Registro<br/>(navigator.credentials.create)"]

            Browser & App --> OpType
            OpType --> Login
            OpType --> Reg
        end

        %% Layer 5: Sub-types & Complexity
        subgraph Modality ["Capa 5: Modalidad y Complejidad"]
            Sub_CUI["CUI / UI Condicional"]
            Sub_Auto["Operación automática"]
            Sub_CDA["CDA / Autenticación entre dispositivos"]

            Login & Reg --> Sub_CUI
            Login & Reg --> Sub_Auto
            Login & Reg --> Sub_CDA
        end
    end

    %% --- BOTTOM: CLASSIFICATION & ACTION (The "What here?" section) ---
    subgraph Analysis ["Análisis de errores y tiempo de ejecución"]
        direction TB

        %% Classification
        Classification{"Clasificación"}

        Exp["Error esperado<br/>(Usuario abortó la ceremonia)"]:::expected
        Unexp["Error inesperado<br/>(Sistema/Fallo/Desconocido)"]:::unexpected

        ClientManifest --> Classification
        Sub_CUI & Sub_Auto & Sub_CDA --> Classification

        Classification --> Exp
        Classification --> Unexp

        %% Detection Logic
        subgraph Detection ["Objetivos de detección"]
            P1["P1: Problemas de inicio de sesión"]
            P2["P2: Problemas de creación"]
            Baseline["Detectar deriva de la línea base<br/>(Aumento de lo esperado)"]
            NewErr["Detectar nuevas anomalías<br/>(Aumento de lo inesperado)"]
        end

        Exp --> Baseline
        Unexp --> NewErr
        Exp & Unexp --> P1 & P2

        %% Actionable Outcomes
        subgraph Action ["Acciones de mitigación"]
            Fix["Implementar parche (hotfix) / Nueva versión"]:::action
            Fallback["Activar alternativa automática<br/>(Desactivar clave de acceso)"]:::action
        end

        P1 & P2 & NewErr --> Fix
        P1 & P2 & NewErr --> Fallback
    end

    %% Connectors
    Infrastructure -.-> Environment

La idea clave: un error.name sin procesar solo tiene sentido una vez que se sabe qué capa del Entorno lo produjo, qué Operación se estaba ejecutando y si el error fue Esperado o Inesperado. Las secciones a continuación cubren qué registrar y cómo actuar en consecuencia.

La mayor parte de la clasificación de errores de este artículo puede realizarse únicamente con señales del lado del cliente. Un SDK de observabilidad exclusivamente frontend (frontend-only) captura el contexto suficiente para clasificar la inmensa mayoría de los errores de WebAuthn. Así es también como está diseñado el SDK de observabilidad de Corbado: la capa del lado del cliente se encarga de la atribución de errores, los tiempos, el contexto de las operaciones y la detección de plataformas. El registro (logging) del lado del servidor añade una segunda capa para los fallos que solo el backend puede ver.

El requisito clave: cada intento debe poder unirse de extremo a extremo (end-to-end). Un id de correlación compartido (por ejemplo, auth_flow_id) conecta el contexto del lado del cliente con el resultado de la verificación del servidor.

Los errores en la verificación del servidor ocurren después de que el navegador retorna una credencial y un desafío firmado. Deberían ser errores estructurados con códigos explícitos, sin mezclarse en el mismo conjunto que los nombres de DOMException del lado del cliente. Vea: implementación del servidor WebAuthn.

Si desea un modelo de embudo completo (abandonos por paso y conversión entre pasos), consulte: telemetría de claves de acceso para comprender los abandonos.

Suscríbete a nuestro Substack de passkeys para recibir las últimas noticias.

Suscribirse

Con estos datos, la conclusión es simple: la mayoría de los “errores” se convierten en correcciones de UX, correcciones de cobertura o correcciones de configuración. Sin embargo, construir y mantener esta clasificación usted mismo es un trabajo continuo significativo.

La lista de comprobación de registros (logging checklist) anterior captura señales en bruto. En producción a escala, error.name por sí solo no es suficiente. Construir esta clasificación uno mismo supone un importante trabajo continuado: los mensajes de error cambian con cada versión del navegador y del sistema operativo, los proveedores de gestores de contraseñas publican actualizaciones que alteran el comportamiento en la ceremonia y las nuevas firmas de errores aparecen con cada lanzamiento de funcionalidades.

El mismo NotAllowedError puede significar seis cosas distintas en función de tres dimensiones que los navegadores no separan por usted:

Este es el problema que el SDK de observabilidad de Corbado fue creado para resolver. Se trata de una integración frontend ligera que se asienta sobre su actual implementación de claves de acceso, trabaja con cualquier servidor WebAuthn y con cualquier IDP, y clasifica cada error de WebAuthn en función de sus tres dimensiones de forma automática:

Esta es la capa Observe: visibilidad sobre lo que está ocurriendo, sin tener que cambiar su implementación.

La consola de administración de Corbado admite dos vías de investigación:

Top-down (del dashboard a la causa de raíz):

1. Supervisar en busca de dos tipos diferentes de anomalías:
   • Aumento de Errores Esperados (Deriva de la Línea Base): ¿Ha habido en un determinado entorno específico (por ejemplo, un iOS 18.2 de un iPhone 15) un aumento gradual de "cancelaciones por el usuario"? Esto suele indicar una fricción en la UX fruto de la actualización del sistema operativo.
   • Aumento de Errores Inesperados (Picos): Un error totalmente nuevo o un incremento repentino de los fallos. Esto casi siempre indica que se ha producido algún cambio que rompe la aplicación (una actualización del stack interno del IDP) o una regresión en la nueva versión de un navegador.
2. Priorizar según su impacto:
   • P1: Problemas de Inicio de Sesión. En caso de que bajen las tasas de éxito de los inicios de sesión, enviar una alerta de inmediato.
   • P2: Problemas de Creación. Vigile las tendencias, pero trate de evitar el despertar a los ingenieros si hay picos del "usuario cancelado" en los flujos de creación.
3. Profundice hacia el Entorno: Utilice sus dimensiones pormenorizadas (hardware, configuración de autenticación) con la finalidad de poder aislar si el problema es de tipo global, o de si es algo propio de "dispositivos Samsung que utilizan Android 14".
4. Mitigación: Tenga listo su Kill Switch (interruptor) si ve que se detecta un pico de forma crítica. Debe desactivar las passkeys -automática o manualmente- para el entorno en concreto, recurriendo de nuevo a las contraseñas/OTPs, logrando preservar de esta forma el nivel en la tasa de inicios de sesión mientras que realiza la investigación.

Bottom-up (desde los patrones de error hasta llegar al impacto):

1. Arranque empezando por la vista donde se clasifican todos los errores. Efectúe revisiones de esos patrones de errores que ya tiene clasificados junto con sus respectivos volúmenes.
2. Ajuste (y vaya refinando) el mapeo de los errores a medida en la que vayan aflorando los nuevos patrones (por ejemplo: la nueva versión de un navegador emite su propio mensaje de error).
3. Los errores estarán correlacionados con los diferentes cambios realizados en los KPIs para aparecer luego resaltados a través de anotaciones hechas en el panel, en consecuencia, todo pico producido por un patrón especifico de un error es vinculado de forma automática con el respectivo medidor al que terminó por afectar.

Las dos rutas convergen: de arriba hacia abajo (top-down) te estará diciendo si algo no funciona de forma debida, desde abajo hasta arriba (bottom-up) te revelará su porqué. El AI Analytics Assistant conecta a ambos permitiéndole la realización de las correspondientes consultas en un lenguaje natural en el caso de los datos provenientes de errores, y todo ello lo hará transversalmente frente a aquellas otras métricas empleadas respecto a su adopción.

Los equipos que deseen procesar de un modo proactivo el poder accionar sobre aquellas señales en concreto, pueden pasarse a la fase Adopt, sumando por ello y con ello inteligencia a la clave de acceso de cara al filtrado (a modo de acceso/gate) sobre sus propias ceremonias, o a ser capaz de la optimización que permita unas solicitudes más óptimas en materia de inscripciones a su vez sumado al poder revertir el caso de claves de acceso corrompidas. En el contexto propio al entorno regulado, así como a ese tan particular para todos esos de sus mismos despliegues que operan con características propias del formato híper-escalado, se adicionará al conjunto Enterprise la opción por la de realizar unos hospedajes que dispongan en consecuencia, a su propio inquilino exclusivo (single-tenant), así como de la total integración en cuanto se le precisa hacia todo ese marco en lo del SIEM así mismo conjuntamente al lado por medio de una de aquellas propias por las que se atenga propiamente del total ajustado por ende a la configuración PSD2.

Obtén un whitepaper gratuito de passkeys para empresas.

Obtener gratis

Los nombres de error de WebAuthn no son un veredicto final. Son pistas, y solo se vuelven accionables cuando los conecta al tipo de operación, el tiempo y el contexto de la plataforma.

• ¿Qué significan en producción los nombres de error más comunes de WebAuthn? La mayoría se mapean a un pequeño conjunto de capas: flujo de control del usuario (NotAllowedError), ciclo de vida/concurrencia de la aplicación (AbortError), configuración/contexto de seguridad (SecurityError), o errores de opción/estado (InvalidStateError, ConstraintError, DataError). La gran mayoría del volumen es NotAllowedError, y la mayor parte de eso es comportamiento esperado (el usuario descartó el aviso).
• ¿Cómo se desambigua NotAllowedError? Utilice el tiempo (rechazo inmediato frente a la cancelación del usuario frente a tiempo de espera), un indicador de código QR/híbrido (desajuste de disponibilidad), el contexto de activación del usuario (especialmente en iOS/Safari) y el tipo de operación (interfaz de usuario condicional vs inicio de sesión modal vs creación de claves de acceso vs creación condicional). No trate todos los NotAllowedError como el mismo modo de fallo.
• ¿Por qué importa el tipo de operación? El mismo error.name durante un inicio de sesión de interfaz de usuario condicional es una señal completamente diferente que durante una creación condicional o una creación manual de claves de acceso (el usuario cerró el cuadro de diálogo). Registrar el tipo de operación junto con el error es lo que convierte al genérico NotAllowedError en una categoría accionable.
• ¿Qué contexto mínimo hace que los errores sean depurables? Capture error.name, el tipo de operación, el tiempo de error desde el inicio de la operación, el tipo de flujo, si se mostró la interfaz de usuario de código QR/híbrida, SO/navegador/dispositivo (incluidas las versiones), un id de correlación (auth_flow_id) y rechazos de verificación del servidor como códigos explícitos.

Dos reglas empíricas que aplican en todos los tipos de errores: nunca muestre errores nativos del navegador a los usuarios (siempre proporcione una ruta alternativa clara) y separe los intentos locales de los intentos de dispositivos cruzados de código QR/híbrido, ya que fallan por razones diferentes y requieren correcciones diferentes. A escala, mantener la clasificación de errores en navegadores, versiones de sistemas operativos y administradores de credenciales es un trabajo continuo. Considere la posibilidad de utilizar un SDK de observabilidad con una biblioteca de patrones mantenida en lugar de construir esto desde cero.

Acerca de Corbado

Corbado es la Authentication Intelligence Platform para equipos de CIAM que gestionan autenticación de consumidores a gran escala. Te ayudamos a ver lo que los logs de tu IDP y las herramientas de analytics genéricas no muestran: qué dispositivos, versiones de SO, navegadores y gestores de credenciales soportan passkeys, por qué los registros no se convierten en inicios de sesión, dónde falla el flujo de WebAuthn y cuándo una actualización de SO o navegador rompe el login en silencio — todo sin reemplazar Okta, Auth0, Ping, Cognito o tu IDP propio. Dos productos: Corbado Observe aporta observabilidad para passkeys y cualquier otro método de login. Corbado Connect añade passkeys gestionados con analytics integrado (junto a tu IDP). VicRoads ejecuta passkeys para más de 5M de usuarios con Corbado (+80 % de activación de passkey). Habla con un experto en Passkeys →

En la web, por motivos de privacidad, los navegadores combinan ambos casos en NotAllowedError, por lo que no se pueden distinguir directamente. Utilice el tiempo como indicador: un error por debajo de 1 segundo normalmente significa un rechazo del entorno o falta de capacidad, mientras que entre 1 y 15 segundos sugiere que el usuario vio y descartó el cuadro de diálogo. En las aplicaciones nativas de iOS y Android, configurar preferImmediatelyAvailableCredentials antes de la solicitud le brinda una señal limpia de "sin credenciales" (código 1005 en iOS, GetCredentialRequest en Android) antes de que se muestre cualquier interfaz de usuario.

En implementaciones optimizadas de claves de acceso a gran escala, más del 95 % de los errores de WebAuthn registrados son abortos esperados de los usuarios, no fallos del sistema. Hacer un seguimiento de los recuentos sin procesar de error.name sin separar "el usuario descartó el aviso" de los fallos genuinos infla las métricas de error y oculta las regresiones reales que se esconden dentro del volumen de NotAllowedError. Divida sus recuentos por tipo de operación y trate las categorías de cancelación del usuario por separado de los errores inesperados como SecurityError, ConstraintError y DataError.

El código 1005 de iOS (NotInteractive) significa que no había ninguna clave de acceso disponible en el dispositivo cuando se estableció preferImmediatelyAvailableCredentials en ASAuthorizationController, y no se le mostró ninguna interfaz de usuario al usuario. Esta es la señal clara de "no existe ninguna clave de acceso en este dispositivo" que los navegadores web no pueden proporcionar debido a las restricciones de privacidad. Clasifique siempre en función del código numérico, no de localizedDescription, porque los mensajes de Apple están localizados en más de 30 idiomas y pueden cambiar en las distintas versiones del sistema operativo.

Durante la creación condicional, NotAllowedError, AbortError e InvalidStateError son resultados esperados y deben ignorarse silenciosamente en lugar de mostrarse como errores. NotAllowedError indica que la función de autocompletar no está disponible o que la página perdió el foco, mientras que InvalidStateError significa que ya existe una clave de acceso en el proveedor. Antes de intentar la llamada, utilice getClientCapabilities() para verificar la compatibilidad con conditionalCreate y compruebe el estado de visibilidad del documento para evitar inflar sus recuentos de errores.

Capture el tipo de operación (interfaz de usuario condicional, inicio de sesión modal, creación manual, creación condicional o adición automática), el tiempo hasta el error desde el inicio de la operación, la versión del sistema operativo, la versión del navegador, el modelo de hardware, si apareció la interfaz de usuario de código QR/híbrida y un identificador de correlación para unirse con los registros del lado del servidor. Los fallos de verificación del servidor, como la falta de coincidencia del desafío, una firma no válida y la credencial no encontrada, deben registrarse como códigos estructurados explícitos, no mezclados en la misma categoría que los nombres de DOMException del lado del cliente. Estas señales juntas permiten clasificar la gran mayoría de los errores en categorías accionables sin tener que adivinar.