Panduan Lengkap Kesalahan WebAuthn di Produksi (2026)

Di lingkungan produksi, kesalahan WebAuthn membingungkan karena browser mengekspos sekumpulan kecil nama DOMException (seperti NotAllowedError) yang dapat mewakili berbagai penyebab yang mendasarinya. Selain itu, sebagian besar "kesalahan" - sering kali di atas 95% dalam penerapan kunci sandi skala besar yang dioptimalkan - sebenarnya merupakan perilaku yang diharapkan (pengguna membatalkan prompt kunci sandi sistem operasi).

Eksperimen dengan alur passkey di Passkeys Debugger.

Coba gratis

Jika Anda menginginkan definisi kanonis untuk nama-nama ini, mulailah dengan MDN DOMException. Untuk kondisi spesifik WebAuthn yang mengarah ke pengecualian ini (dan yang wajib ditegakkan oleh browser), lihat spesifikasi Autentikasi Web W3C.

Jika Anda memperlakukan semua kesalahan sebagai "bug", Anda akan melakukan hal yang salah:

• Anda akan mencemari metrik kesalahan Anda dengan pembatalan normal
• Anda akan melewatkan regresi nyata yang tersembunyi di dalam banyaknya NotAllowedError
• Anda akan mengirimkan UI yang membingungkan pengguna alih-alih membantu mereka memulihkan diri

Dalam artikel ini kami menjawab:

• Apa arti nama kesalahan WebAuthn yang paling umum di lalu lintas nyata?
• Bagaimana Anda membedakan NotAllowedError ke dalam keranjang yang dapat ditindaklanjuti (batal vs waktu habis vs ketersediaan)?
• Mengapa kesalahan yang sama berarti hal yang berbeda bergantung pada operasi (login UI bersyarat vs login modal vs pembuatan kunci sandi vs pembuatan bersyarat)?
• Apa konteks minimum yang harus Anda tangkap sehingga "itu gagal" menjadi masalah yang dapat direproduksi?

Jika Anda hanya membutuhkan pemetaan cepat untuk membebaskan proses debug, mulailah dengan tabel ini. Ini berpihak pada apa yang sebenarnya dilihat tim di dasbor dan tiket dukungan.

Satu hal yang mudah terlewatkan: error.name yang sama bisa berarti hal yang sangat berbeda bergantung pada tipe operasi. Tetap ingat konteks operasi saat Anda membaca bagian di bawah ini. Praktiknya, kesalahan pembuatan kunci sandi (pendaftaran) biasanya jauh melebihi jumlah kesalahan login - tabel di atas berlaku untuk keduanya, tetapi pembuatan adalah tempat sebagian besar volume berada.

Selanjutnya, kita akan membahas lebih dalam NotAllowedError karena itu adalah salah satu yang paling sering Anda lihat dan yang sering salah diartikan tim.

NotAllowedError sering terlihat seperti "kunci sandi gagal", tetapi biasanya itu adalah platform yang memberi tahu Anda bahwa pengguna tidak menyelesaikan UI OS. Kuncinya adalah membaginya menjadi keranjang yang dapat Anda tindaklanjuti.

Apa yang akan Anda lihat di konsol browser:

Semua ini muncul sebagai error.name === "NotAllowedError". error.message berbeda menurut mesin browser dan penyebab yang mendasari, namun hasilnya sama: upacara tidak selesai.

Ini berlaku untuk login dan pembuatan kunci sandi. Selama login (UI bersyarat, modal dengan atau tanpa daftar yang diizinkan), NotAllowedError biasanya berarti pengguna tidak menyelesaikan upacara. Selama pembuatan kunci sandi, kesalahan yang sama muncul karena alasan yang berbeda: pengguna mengabaikan dialog pembuatan (pembuatan bersyarat tidak berfungsi, atau halaman kehilangan fokus selama penambahan yang dipicu secara otomatis. Tipe operasi mengubah makna kesalahan dan apa yang harus Anda lakukan tentangnya.

Pengaturan waktu sering kali merupakan sinyal yang diremehkan. Kegagalan setelah kurang dari satu detik klik adalah biasanya penolakan langsung (lingkungan tidak bisa melakukannya, dokumen tidak difokuskan, kemampuan hilang). Kesalahan setelah beberapa detik adalah pembatalan pengguna (mereka melihat dialog dan memutuskan untuk tidak melanjutkan). Kesalahan setelah 30+ detik adalah batas waktu. Pada platform native, pengaturan waktu sangat penting: perjalanan autentikator pulang pergi, prompt biometrik dan penyerahan pengelola kredensial semuanya memiliki durasi karakteristik yang membantu Anda memisahkan "tidak berfungsi" dari "pengguna pergi". Anda masih tidak dapat membedakannya dengan mudah jika kunci sandi ada.

Anda tidak memerlukan sinyal yang sempurna. Anda memerlukan konteks yang cukup untuk menghindari memperlakukan setiap NotAllowedError dengan cara yang sama. iOS/Safari mendapatkan perhatian khusus di bawah ini karena ia memiliki kendala unik (persyaratan aktivasi pengguna di versi sebelumnya), namun dalam volume kesalahan mentah, Windows dan Chromium browsers sering menghasilkan lebih banyak NotAllowedError daripada platform lainnya. Sinyal-sinyal ini sering membuat Anda mendapatkan 80% dari cara:

Inilah juga mengapa NotAllowedError jarang terlihat oleh pengguna. Ini bukan pesan yang dapat ditindaklanjuti oleh pengguna.

Klasifikasi konteks juga merupakan titik pembagian tingkat keberhasilan secara tajam. Analisis tingkat keberhasilan autentikasi kunci sandi Tolok Ukur Kunci Sandi Corbado 2026 mengukur penyelesaian Q1 2026 sebesar 55–95% untuk alur pengidentifikasi-pertama perangkat yang tidak dikenal versus 95–99% untuk pengembalian perangkat yang dikenal di seluruh penerapan B2C skala besar. Pengidentifikasi-pertama web iOS mendarat di penyelesaian 85–95% (% CDA 0–5%), web Android pada 70–85% (% CDA 5–10%) dan web macOS pada 70–85% (% CDA 10–15%), sementara web Windows duduk di 45–60% penyelesaian pengidentifikasi-pertama dengan % CDA di 55–65% pada Windows 11 dan 40–55% pada Windows 10. Membaca volume NotAllowedError tanpa memisahkan konteks perangkat yang dikenal versus perangkat yang tidak dikenal menggabungkan dua rezim keberhasilan yang secara mendasar berbeda.

Satu nuansa yang penting dalam produksi: beberapa user agent dapat memunculkan batas waktu sebagai TimeoutError, namun banyak tim masih melihat batas waktu mengerucut menjadi NotAllowedError di dasbor. Bagaimanapun, perlakukan batas waktu sebagai “upacara tidak selesai” dan kelompokkan menggunakan waktu beserta konteks.

Ketika lembar OS diabaikan atau habis waktunya, UI Anda harus segera pulih dan bereaksi dengan baik. Serangkaian aturan praktis:

• kembalikan UI masuk (jangan ada pemutar yang terus berjalan)
• pertahankan status pengenal (jangan memaksa masuk kembali)
• tampilkan alternatif yang terlihat di layar yang sama
• hindari spanduk menakutkan untuk hasil yang diharapkan

Di luar hal dasar:

• Perlakukan pembatalan pertama sebagai hal biasa dan tawarkan opsi coba lagi dengan penjelasan yang tenang. Hanya setelah pembatalan kedua Anda harus menyarankan opsi alternatif (lihat cadangan dan pemulihan kunci sandi).
• Izinkan maksimal tiga prompt pembuatan sebelum jeda waktu agar pengguna yang terkejut mendapat kesempatan kedua (lihat praktik terbaik pembuatan kunci sandi).
• Pisahkan jumlah kesalahan antara pembuatan dan masuk agar Anda membandingkan apel dengan apel.
• Kelompokkan tingkat kesalahan berdasarkan OS, browser, dan perangkat agar Anda dapat melihat di mana sebenarnya hambatan terjadi (lihat praktik terbaik masuk kunci sandi).

Jika "pembatalan" Anda benar-benar tinggi, langkah selanjutnya adalah memperbaiki akar masalah di baliknya: waktu perintah, kejutan QR, dan ketersediaan yang rendah.

Mulai dengan perubahan yang memindahkan metrik dengan cepat:

• Perbaiki pengaturan waktu perintah dan aktivasi pengguna (terutama pada iOS/Safari): Kejadian yang diaktifkan pengguna WebAuthn Safari.
• Kurangi kejutan QR/hybrid: mengapa alur passkey menunjukkan kode QR dan pengguna meninggalkannya.
• Batasi tawaran agar passkey ditampilkan saat kemungkinan besar berhasil: tawarkan passkey hanya bila kemungkinan besar akan berhasil.
• Gunakan pola yang menghindari permintaan saat tidak ada kredensial lokal: Mediasi segera WebAuthn.
• Tangani Ketidakstabilan Jaringan: Kesalahan jaringan selama verifikasi sering kali terwujud sebagai kegagalan klien yang generik. Terapkan antrean offline untuk pencatatan telemetri Anda sehingga Anda tidak kehilangan data kesalahan saat koneksi pengguna terputus selama upacara berlangsung.
• Batasi upacara dengan API deteksi sehingga kegagalan lingkungan tidak menggelembungkan keranjang NotAllowedError Anda. Mulai dengan isUVPAA() sebagai pembatas paling dasar, lalu gunakan getClientCapabilities() untuk pemeriksaan yang lebih baik (pembuatan bersyarat, penerimaan bersyarat, transportasi hybrid, pengautentikasi platform). Perhatikan bahwa API deteksi dapat rusak pada pembaruan OS: iOS 26.2 meluncurkan bug WebKit di mana isUVPAA() menghasilkan false pada semua browser berbasis WKWebView meskipun passkey berfungsi dengan baik, menyebabkan lonjakan NotAllowedError mendadak bagi 10-25% pengguna iOS (lihat memperbaiki deteksi passkey dengan getClientCapabilities()).

Nama-nama kesalahan adalah target yang bergerak. Ada berbagai proposal berkelanjutan untuk menambah rincian kesalahan WebAuthn (misalnya, untuk memisahkan “tidak ada kredensial yang tersedia” dari “pengguna yang membatalkan”). Sejak Februari 2026, hal tersebut belum diterapkan di dalam sebagian besar peramban, jadi ada baiknya membangun keranjang alasan Anda sendiri berdasarkan konteks dan waktu. Bila Anda ingin melacak pekerjaan ini, lihat WebAuthn issue #2062 dan penjelas "Kode Kesalahan Baru".

Nama-nama kesalahan lainnya kurang sering terjadi namun tetap berguna untuk dipahami bila muncul.

AbortError tidak umum dalam volume jika dibandingkan dengan NotAllowedError, tetapi saat muncul ini sangat diagnostik: ini biasanya berarti upacara tidak selesai karena aplikasi Anda membatalkan permintaan - navigasi terjadi, state berubah, atau permintaan kedua dimulai.

Apa yang akan Anda lihat di konsol browser:

Penyebab umum produksi meliputi:

• beberapa panggilan WebAuthn serentak (dua prompt balapan)
• perubahan rute/perenderan ulang saat upacara yang sedang berlangsung
• memanggil AbortController.abort() selama pencobaan ulang atau pembersihan status

Untuk memperbaikinya, berfokuslah untuk menjadikan upacara sebagai "bagian kritis":

• hanya bolehkan satu permintaan dalam proses secara bersamaan
• blokir navigasi selama upacara (atau batalkan secara bersih dan pulihkan UI)
• perlakukan pembatalan sebagai aliran kendali yang diharapkan: tampilkan tombol coba lagi dan metode alternatif

Jika Anda melihat AbortError terkonsentrasi di permukaan yang disematkan atau aplikasi multimesin, hal berikutnya yang harus diperiksa adalah SecurityError.

SecurityError adalah browser yang memberitahu Anda: "konteks ini tidak diizinkan untuk melakukan yang Anda minta." Dalam praktik, hampir selalu soal konfigurasi, bukan perilaku pengguna. Pada pengerahan produksi yang sudah matang, SecurityError langka terjadi karena masalah ini umumnya sudah tertangkap saat tes integrasi. Jika ini muncul di produksi, umumnya hal ini berarti ada penambahan domain baru, penyematan konteks, atau sasaran pengerahan yang dilakukan tanpa konfigurasi WebAuthn yang tepat.

Penyebab-penyebab umum termasuk:

• RP ID / kegagalan kecocokan muasal (setelan multi-domain)
• larangan penyematan asalan-bersilang (iframe)
• konteks tidak aman (bukan HTTPS) atau terblokirnya hak/kebijakan
• .well-known/webauthn atau .well-known/assetlinks.json salah konfigurasi, hilang, atau tidak tersedia sementara. Isu jaringan saat terjadi kondisi krusial yang saat mana browser mengambil berkas-berkas ini bakal menimbulkan kegagalan. Satu rupa buta yang umum: jika halamamuka Anda turun untuk di-maintenance, berkas-berkas well-known juga ikutan offline, lantas merusak perayaan kunci sandi lintas seluruh pihak-tergantung yang memerlukannya.

Apa yang bakal Anda lihat dalam konsol browser:

Dalam produksi, SecurityError langka terjadi - ini lumrah tertangkap saat tes integrasi. Ketika ini terjadi, kesalahan sertifikat TLS yang paling umum bertahan hidup.

Loop debugging paling cepat adalah:

• masuk pada asal dan RP ID masukan yang Anda gunakan
• perbanyak dalam konteks sama (top-level vs iframe, prod domain vs staging)
• jika Anda menyematkan log-masuk, tetapkan kebijakan izin sudah di-setel (misalnya publickey-credentials-create / publickey-credentials-get): MDN Permissions-Policy
• pastikan taktik domain Anda (lihat asal berkaitan)
• jika Anda memakai iframe, validasi kebijakan fiturnya (lihat kunci sandi iframe)

Setelah SecurityError di-urus, wadah selanjutnya yang patut ditangani secara serius adalah rangkaian kesalahan yang menandakan bug penerapan: InvalidStateError, ConstraintError serta DataError.

Cheatsheet Passkeys. Panduan praktis, pola peluncuran, dan KPI untuk program passkeys.

Dapatkan cheat sheet

Kesalahan-kesalahan ini harus langka dalam implementasi kunci sandi yang matang. Jika muncul, mereka biasanya menunjukkan bahwa opsi generasi salah untuk suatu segmen atau aliran ada dalam keadaan salah.

Apa yang akan Anda lihat di konsol browser:

Arti tipikal:

• pendaftaran: Anda mencoba untuk membuat kredensial yang sudah ada (duplikat)
• log masuk: kurang umum; seringkali berarti alur/keadaan inkonsisten untuk platform tersebut

Penanganan praktis:

• jika terjadi pada registrasi manual, perlakukan sebagai "sudah terdaftar" dan rutekan secara tepat
• pastikan excludeCredentials mencantumkan seluruh ID kredensial eksisten untuk pengguna sehingga autentikator dapat mendeteksi duplikat (lihat excludeCredentials)
• selama pembuatan kondisional, InvalidStateError merupakan harapan dan sebaiknya diabaikan dalam diam: artinya sebuah kunci sandi sudah eksis dalam provider. Hal yang sama juga berlaku untuk NotAllowedError dan AbortError selama pembuatan kondisional (lihat conditional create on Chrome)

Arti Umum: authenticator tidak dapat memenuhi kendala yang Anda minta.

Pemicu umum:

• penguncian layar perangkat hilang (terutama Android): platform membutuhkan verifikasi biometrik atau PIN, tetapi perangkat tersebut tidak mempunyai layar kunci yang dikonfigurasi
• authenticatorAttachment terlalu ketat atau kunci residen asumsi
• kendala userVerification pada segmen-segmen di mana hal tersebut tidak tersedia

Memperbaiki: ringankan kendala (jika dimungkinkan) atau tawarkan rute alternatif. Untuk layar kunci yang hilang, pertimbangkan pendeteksian kondisi ini lalu arahkan user ketimbang membiarkan kegagalan berlalu tanpa notifikasi (Android).

Arti khas: masukan tidak berbentuk dengan baik atau inkonsisten.

Pemicu yang lazim:

• kesalahan pada saat penyandian (base64 vs base64url)
• id kredensial yang cacat / tantangan pada pemformatan

Solusi: validasi dan normalisasi masukan di perbatasan tempat Anda mengonfigurasi WebAuthn opsional. Dalam penerapannya, DataError secara praktis ditiadakan di dalam platform sistem pengerjaan—seandainya pembuatan pilihan Anda telah diuji, Anda takkan melihatnya di panel informasi Anda.

Kala semua kesalahan ini ditangani, kendala berikutnya adalah tentang jangkauan: apakah user tak dapat menaut karena gawai yang dipakai tidak sesuai dengan dukungan WebAuthn yang Anda rancang?

NotSupportedError adalah sinyal cakupan, bukan sinyal keandalan. Biasanya ini berarti suatu segmen tidak dapat melakukan apa yang Anda minta (versi OS/browser terlalu lama, kemampuan tidak ada, fitur tidak diaktifkan).

Apa yang akan Anda lihat di konsol browser:

Dua hal pertama adalah DOMException NotSupportedError asli. Entri TypeError secara teknis adalah tipe pengecualian yang berbeda tetapi mewakili kelas masalah yang sama: browser atau lingkungan tidak mendukung apa yang Anda minta. Rumpun TypeError serialisasi JSON jauh lebih umum dalam praktiknya daripada DOMException NotSupportedError itu sendiri (lihat di bawah).

Penyebab umum meliputi:

• versi browser/OS lama yang tidak mendukung dasar WebAuthn
• meminta fitur WebAuthn yang tidak tersedia di platform tersebut
• mencoba alur platform-spesifik di perangkat yang tidak didukung

Rumpun serialisasi JSON adalah sumber terbesar dari kegagalan kelas NotSupportedError di produksi. Secara teknis ini muncul sebagai TypeError (metode hilang), bukan sebagai DOMException, tetapi di sinilah Anda akan menemukannya. Dua penyebab dasar berbeda:

1. Browser tidak mendukung metode serialisasi JSON WebAuthn. Browser memiliki navigator.credentials tetapi bukan PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON. Ini merupakan sekitar 90% dari rumpun kesalahan ini, terkonsentrasi pada versi Safari dan Chrome lama. Jika perpustakaan klien Anda bergantung pada metode ini tanpa cadangan, ini menghasilkan volume kesalahan yang signifikan.
2. Ekstensi pengelola kata sandi merusak .toJSON(). Ekstensi seperti Bitwarden, LastPass, atau 1Password dapat mencegat upacara dan mengembalikan objek yang terlihat seperti kredensial tetapi bukan instance PublicKeyCredential yang sebenarnya. Memanggil .toJSON() padanya akan gagal, mengembalikan tidak terdefinisi, atau objek tersebut null seluruhnya. Ini adalah sekitar 10% dari rumpun tetapi terutama membingungkan untuk debug karena pesan kesalahan berbeda menurut browser (Safari: "Can only call on instances of PublicKeyCredential"; Firefox: "does not implement interface PublicKeyCredential").

Penanganan harus tegas dan cepat:

• segera kembali ke kata sandi/OTP cadangan
• catat segmen sehingga Anda dapat mengukur kesenjangan cakupan
• hindari menampilkan CTA passkey pada segmen yang akan selalu gagal

Jika cakupan terlihat baik tetapi kegagalan masih terjadi pada segmen tertentu, Anda mungkin menghadapi masalah lapisan platform yang muncul sebagai UnknownError.

UnknownError adalah serba-bisa untuk kegagalan autentikator/OS yang tidak dipetakan secara jelas ke dalam kategori lain. Ini sering kali sementara, tetapi juga dapat melonjak setelah pembaruan OS.

Apa yang akan Anda lihat di konsol browser:

Penanganan praktis:

• gunakan UX yang ramah untuk mencoba lagi (jangan "menyalahkan pengguna")
• ambil OS/nomor build dan konteks credential-manager/provider di mana dimungkinkan
• waspadai lonjakan spesifik segmen setelah pembaruan OS

Satu sumber kesalahan yang unik dan tidak masuk secara rapi ke dalam kategori DOMException mana pun: ekstensi browser manajer kata sandi (seperti Bitwarden, LastPass, 1Password, dan lain-lain) dapat mencegat panggilan API WebAuthn dan mengembalikan tanggapan non-standar. Meskipun kecil dalam volume dibandingkan dengan pembatalan pengguna, kesalahan ini berharga untuk dilacak karena mereka memengaruhi segmen pengguna tertentu secara konsisten dan gejala-gejalanya membingungkan: metode yang hilang dari objek kredensial yang dikembalikan, tipe kesalahan yang tidak terduga, atau tanggapan cacat yang tidak cocok dengan satupun kesalahan WebAuthn yang terdokumentasi. Kesalahan-kesalahan ini sering kali timbul sebagai UnknownError atau sebagai pengecualian yang tidak terklasifikasi. Jika Anda melihat adanya lonjakan kesalahan yang terkonsentrasi di dalam peramban tertentu tanpa alasan dari OS itu sendiri, periksa apakah suatu ekstensi manajer kredensial terkait.

Selama ini kami hanya meliputi penamaan kesalahan penjelajah peramban saja. Tetapi jika Anda juga mengekspor aplikasi lokal, maka pemandangan kesalahan pun turut menjadi lain - serta dalam sedikit hal, lebih berarti.

Segala hal di atas mencakup peramban web. Aplikasi native - iOS dengan rangka ASAuthorization, Android beserta Manajer Kredensial - membagikan rumpun kesalahan sama pada kategori dasar mereka melainkan agak sedikit berbeda dalam arti yang lebih luas:

1. "Tidak ada kredensial" adalah sinyal yang berbeda. Di web, peramban menyatukan "tidak ada kredensial yang tersedia" dan "pengguna membatalkan" ke dalam NotAllowedError yang sama demi privasi. Di ranah native, menggunakan preferImmediatelyAvailableCredentials di iOS (ASAuthorizationController) atau setPreferImmediatelyAvailableCredentials(true) di Android (GetCredentialRequest) akan memberitahukan OS hanya untuk menyajikan kredensial yang sudah ada di perangkat dan langsung gagal jika tidak ada kredensial tersebut. Ini memberi Anda kembalian "tanpa kredensial" yang bersih, sesuatu yang tidak dapat diberikan oleh web.

2. Status penyedia kredensial tampak. Platform native dalam beberapa kondisi dapat memberitahu Anda jika tidak ada penyedia kredensial (Google Password Manager, iCloud Keychain, 1Password, dll.) yang dipasang, dikonfigurasi, atau disetel sebagai nilai default lalu bereaksi terhadapnya. Pada web, informasi ini tersembunyi di balik pesan buram NotAllowedError.

3. Pesan kesalahan lebih spesifik. Oleh karena sang pengguna telah memasang aplikasi tersebut - dan dengannya membuat satu hubungan kepecayaan dengan pihak terkait - maka OS memberi rincian diagnosisnya. Pertimbangan keprivasian yang secara paksa menekan peramban di web agar menyamarkan kesalahannya tidak berlaku sejalan kala pengaplikasian tersebut nyata sudah berada di gawai. iOS menyuguhkan pesan terlokalisasi di dalam gawai berdasarkan preferensi bahasa penggunanya. Android mengantarkan sejenis penataan struktur kesalahan lewat urutan permasalahannya. Karenanya perbaikan jauh lebih ringkas walaupun arti pada hal itu menuntun penanganan yang mengharuskan agar penyetelan dapat melokalisasi bentuk format kesalahan khas-platform.

iOS memunculkan kesalahan kunci sandi melalui kerangka ASAuthorization. Semua kesalahan tiba dalam callback delegasi authorizationController(controller:didCompleteWithError:) sebagai objek NSError.

Klasifikasikan berdasarkan domain + kode, bukan berdasarkan string pesan. Domain kesalahan utama adalah com.apple.AuthenticationServices.AuthorizationError (ASAuthorizationError.errorDomain). Cast kesalahan dengan let nsError = error as NSError dan cocokkan pada .domain dan .code. Jangan pernah mencocokkan pada .localizedDescription di produksi - pesan-pesan Apple dilokalkan ke 30+ bahasa dan dapat berubah seiring versi OS. String pesan yang terdaftar di bawah ini berguna untuk mengenali kesalahan dalam catatan (log), tetapi itu bukanlah kriteria klasifikasi.

Kode ASAuthorizationError Publik:

Perbedaan terpenting pada lingkungan produksi: sejak dirilisnya sistem operasi teranyar itu, jejak duplikasi mengirimkan notifikasi galatnya pribadi berkode 1006 (MatchedExcludedCredential). Dalam penggunaan terdahulu di edisi sebelumnya, sisa duplikat terbungkus jauh di bawah notifikasi Failed (1004). Kini pada platform teranyar ini perbedaannya tersusun (kode yang beda) alih-alih cuma rentetan kalimat.

Masalah umum di masa berjalannya sistem operasi (batas perinci-baca):

Uraian-uraian ini menyingkap di localizedDescription serta userInfo buat kekhususan aneka-salah . Memanfaatkan hal tersebut berguna di penapisan maupun pengusutan dan penelusuran, walau tidak sepadan untuk pembagian berjenjang pada rancang kodenya.

Pesan "tidak ada kredensial" lokal (kode 1005):

Bila preferImmediatelyAvailableCredentials ditetapkan dan tak terdapat sandi, iOS memberi kembalian galat berkode 1005 (NotInteractive) berwujud kabar terlokalkan ke dalam bahasa asli sang pengguna yang tersetel pada gawai kepunyaannya. Cuma ini yang dapat ditemui bagi perangkat tersemat secara bawan—mesin penjelajah pun urung memunculkannya sekelumit juga. Keterangan tersebut senantiasa diawali kalimat The operation couldn't be completed. (Bahasa Inggris) beriring teks tertata berdasarkan lokalisasinya di antaranya:

Perangkat dengan lokal bahasa Inggris biasanya menyelesaikan "tidak ada kredensial" di level API sebelum kerangka kerja ASAuthorization mengembalikan kesalahan yang dilokalkan, itulah sebabnya tidak ada varian bahasa Inggris yang muncul di atas. Secara programatik, selalu cocokkan pada kode 1005 daripada mengurai string ini.

Android memunculkan kesalahan kunci sandi melalui Credential Manager API (androidx.credentials). Pesan kesalahan mencakup pesan utama dan sering kali sebuah cause dengan rincian tambahan. Dibandingkan dengan iOS, Android memberikan tipe kesalahan yang lebih terstruktur dan penyebab yang lebih jelas untuk masalah konfigurasi.

Pembatalan pengguna dan deteksi kredensial:

Kesalahan konfigurasi dan keamanan:

Kesalahan platform dan autentikator:

Diagram berikut ini memperlihatkan bagaimana sekalian tata urutan mulai tingkat Papan Prasarana (Sistem Utama) berujung deteksi hingga tingkatan Operasional terhubung utuh berjenjang atas bawah pada bagannya masing-masing. Gambar bagan di bawah patutnya dibikin konsep tata rancangnya kala berupaya dalam perekaman atas tiap-tiap notifikasi kesalahan yang mengemuka saat terjadinya.

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 ["Infrastruktur (Server/Jaringan)"]
        direction TB
        ServerErr["Kesalahan Sisi Server<br/>500 / Kesalahan Logika"]:::network
        NetErr["Kesalahan Jaringan<br/>Batas Waktu / 400 Bad Request"]:::network

        ServerErr & NetErr -->|Terwujud sebagai| ClientManifest["Kesalahan Generik Sisi Klien"]
    end

    %% --- CENTER: THE ENVIRONMENT STACK (From Sketch) ---
    subgraph Environment ["Lingkungan (Sisi Klien)"]
        direction TB

        %% Layer 1: Platform Type
        subgraph Type ["Lapisan 1: Platform"]
            Web["Web / Browser"]
            Native["Native / Aplikasi"]
        end

        %% Layer 2: OS Context
        subgraph OS_Layer ["Lapisan 2: OS & Versi"]
            OS_Web["OS: Windows, macOS, Linux"]
            OS_Nat["OS: iOS, Android"]
            OS_Ver["Versi OS / Setelan<br/>(Kunci Layar, Biometrik)"]

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

        %% Layer 3: Client Software
        subgraph Client_Layer ["Lapisan 3: Perangkat Lunak Klien"]
            Browser["Browser: Chrome, Safari, Edge<br/>+ Versi"]
            App["Aplikasi Native / WebView<br/>+ Versi Aplikasi"]

            OS_Ver --> Browser
            OS_Ver --> App
        end

        %% Layer 4: WebAuthn Operation
        subgraph Op_Layer ["Lapisan 4: Operasi WebAuthn"]
            OpType{"Jenis Operasi"}

            Login["Login<br/>(navigator.credentials.get)"]
            Reg["Pendaftaran<br/>(navigator.credentials.create)"]

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

        %% Layer 5: Sub-types & Complexity
        subgraph Modality ["Lapisan 5: Modalitas & Kompleksitas"]
            Sub_CUI["CUI / UI Bersyarat"]
            Sub_Auto["Operasi Otomatis"]
            Sub_CDA["CDA / Autentikasi Lintas Perangkat"]

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

    %% --- BOTTOM: CLASSIFICATION & ACTION (The "What here?" section) ---
    subgraph Analysis ["Analisis Kesalahan & Runtime"]
        direction TB

        %% Classification
        Classification{"Klasifikasi"}

        Exp["Kesalahan yang Diharapkan<br/>(Pengguna Membatalkan Upacara)"]:::expected
        Unexp["Kesalahan Tak Terduga<br/>(Sistem/Crash/Tidak Diketahui)"]:::unexpected

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

        Classification --> Exp
        Classification --> Unexp

        %% Detection Logic
        subgraph Detection ["Tujuan Deteksi"]
            P1["P1: Masalah Login"]
            P2["P2: Masalah Pembuatan"]
            Baseline["Deteksi Penyimpangan Baseline<br/>(Peningkatan yang Diharapkan)"]
            NewErr["Deteksi Anomali Baru<br/>(Peningkatan Tak Terduga)"]
        end

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

        %% Actionable Outcomes
        subgraph Action ["Tindakan Mitigasi"]
            Fix["Terapkan Perbaikan Darurat / Versi Baru"]:::action
            Fallback["Aktifkan Fallback Otomatis<br/>(Nonaktifkan Passkey)"]:::action
        end

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

    %% Connectors
    Infrastructure -.-> Environment

Wawasan utamanya: nama error.name mentah hanya masuk akal jika Anda mengetahui di lapisan Lingkungan mana kesalahan itu diproduksi, Operasi mana yang sedang berjalan, dan apakah kesalahan tersebut Diharapkan atau Tidak Terduga. Bagian di bawah ini membahas apa yang harus dicatat dan bagaimana menindaklanjutinya.

Sebagian besar klasifikasi kesalahan dalam artikel ini dapat dilakukan dengan sinyal sisi klien saja. SDK observabilitas sisi klien menangkap cukup konteks untuk mengklasifikasikan sebagian besar kesalahan WebAuthn. Ini juga cara arsitektur SDK observabilitas Corbado: lapisan sisi klien menangani atribusi kesalahan, waktu, konteks operasi, dan deteksi platform. Pencatatan sisi server menambahkan lapisan kedua untuk kegagalan yang hanya dapat dilihat oleh backend.

Persyaratan utamanya: setiap upaya harus dapat digabungkan ujung-ke-ujung (end-to-end). ID korelasi bersama (mis., auth_flow_id) menghubungkan konteks sisi klien dengan hasil verifikasi server.

Kegagalan verifikasi server terjadi setelah browser mengembalikan kredensial dan tantangan yang ditandatangani. Ini harus berupa kesalahan terstruktur dengan kode eksplisit, jangan dicampur ke dalam keranjang yang sama dengan nama DOMException sisi klien. Lihat: Implementasi server WebAuthn.

Jika Anda menginginkan model alur penuh (penurunan pada setiap langkah dan konversi antar langkah), lihat: telemetri passkey untuk memahami penurunan.

Berlangganan Passkeys Substack kami untuk berita terbaru.

Berlangganan

Dengan adanya data ini, kesimpulannya menjadi sederhana: sebagian besar "kesalahan" menjadi perbaikan UX, perbaikan cakupan, atau perbaikan konfigurasi. Namun, membangun dan memelihara klasifikasi ini sendiri merupakan pekerjaan berkelanjutan yang signifikan.

Daftar periksa log di atas menangkap sinyal mentah. Di produksi pada skala besar, error.name saja tidak cukup. Membangun klasifikasi ini sendiri adalah pekerjaan berkelanjutan yang signifikan: pesan kesalahan berubah seiring dengan rilis browser dan OS baru, penyedia pengelola kata sandi mengirimkan pembaruan yang mengubah perilaku upacara dan ciri kesalahan baru muncul dengan peluncuran fitur baru.

NotAllowedError yang sama dapat berarti enam hal yang berbeda bergantung pada tiga dimensi yang tidak dipisahkan oleh browser untuk Anda:

Ini adalah masalah yang dibangun untuk diselesaikan oleh SDK observabilitas Corbado. Ini adalah integrasi antarmuka ringan yang terletak di atas implementasi kunci sandi Anda yang sudah ada, bekerja dengan server WebAuthn mana pun dan IDP apa pun, dan secara otomatis mengklasifikasikan setiap kesalahan WebAuthn ke dalam ketiga dimensi tersebut:

Inilah tingkatan pemantauan (Observe): penampakan ke perkara-perkara internal yang berkisah soal pengamatannya, tanpa turut mengguncang maupun membuat rombakan struktur pada tatanan program buatanmu.

Konsol manajemen Corbado mendukung dua jalur investigasi:

Top-down (dasbor ke akar penyebab):

1. Pantau untuk dua jenis anomali berbeda:
   • Peningkatan Kesalahan yang Diharapkan (Penyimpangan Baseline): Apakah lingkungan tertentu (mis., iOS 18.2 di iPhone 15) mengalami peningkatan bertahap dalam "pembatalan pengguna"? Ini sering menunjukkan gesekan UX yang diperkenalkan oleh pembaruan OS.
   • Peningkatan Kesalahan Tak Terduga (Lonjakan): Kesalahan yang sama sekali baru atau lompatan tiba-tiba kegagalan. Ini biasanya menunjukkan perubahan yang merusak (pembaruan tumpukan IDP internal) atau regresi dalam versi browser baru.
2. Prioritaskan menurut dampak:
   • P1: Masalah Login. Jika tingkat keberhasilan login menurun, segera waspada.
   • P2: Masalah Pembuatan. Pantau tren, tetapi hindari membangunkan teknisi untuk lonjakan "pembatalan pengguna" dalam alur pembuatan.
3. Selidiki Lingkungan: Gunakan dimensi yang lebih rinci (Hardware, Auth Settings) untuk mengisolasi apakah masalah tersebut bersifat global atau spesifik untuk "perangkat Samsung dengan Android 14".
4. Mitigasi: Jika lonjakan kritis terdeteksi, siapkan Kill Switch. Secara otomatis atau manual nonaktifkan kunci sandi untuk lingkungan spesifik itu dan kembali ke OTP/Kata sandi untuk menjaga tingkat login saat Anda menyelidiki.

Bottom-up (pola kesalahan ke dampak):

1. Mulai dari tampilan klasifikasi kesalahan. Tinjau pola kesalahan yang diklasifikasikan dan volumenya.
2. Perbaiki pemetaan kesalahan saat pola baru muncul (mis. versi browser baru yang merilis pesan kesalahan yang berbeda).
3. Kesalahan berkorelasi silang dengan perubahan KPI dan dimunculkan sebagai anotasi di dasbor, sehingga lonjakan dalam pola kesalahan tertentu secara otomatis ditautkan ke metrik yang dipengaruhinya.

Kedua jalur menyatu: top-down memberi tahu Anda ada sesuatu yang salah, bottom-up memberi tahu Anda alasannya. Asisten Analitik AI menghubungkan keduanya dengan memungkinkan Anda mengajukan pertanyaan dalam bahasa alami di seluruh data kesalahan dan metrik adopsi.

Tim yang ingin menindaklanjuti sinyal ini dapat beralih ke Adopt, yang menambahkan intelijen passkey untuk secara otomatis membatasi upacara, mengoptimalkan prompt pendaftaran dan menyembuhkan status passkey yang rusak. Untuk lingkungan yang diatur atau penyebaran skala besar (hyperscale), Enterprise menambahkan hosting penyewa tunggal, integrasi SIEM dan konfigurasi yang mematuhi PSD2.

Dapatkan whitepaper passkey gratis untuk enterprise.

Dapatkan gratis

Nama kesalahan WebAuthn bukan sebuah vonis. Itu adalah petunjuk - dan itu hanya dapat ditindaklanjuti saat Anda menghubungkannya ke jenis operasi, waktu, dan konteks platform.

• Apa arti nama kesalahan WebAuthn yang paling umum di produksi? Sebagian besar memetakan ke sekumpulan kecil lapisan: aliran kontrol pengguna (NotAllowedError), siklus hidup/konkurensi aplikasi (AbortError), konteks/konfigurasi keamanan (SecurityError), atau bug opsi/status (InvalidStateError, ConstraintError, DataError). Sebagian besar volume adalah NotAllowedError, dan sebagian besar dari itu adalah perilaku yang diharapkan (pengguna menutup prompt).
• Bagaimana Anda membedakan NotAllowedError? Gunakan waktu (penolakan instan vs pembatalan pengguna vs batas waktu), indikator QR/hibrida (ketidaksesuaian ketersediaan), konteks aktivasi pengguna (terutama di iOS/Safari) dan jenis operasi (UI bersyarat vs login modal vs pembuatan passkey vs pembuatan bersyarat). Jangan memperlakukan semua NotAllowedError sebagai satu mode kegagalan.
• Mengapa jenis operasi penting? error.name yang sama selama login UI bersyarat adalah sinyal yang sama sekali berbeda dari pada saat pembuatan bersyarat atau pembuatan passkey manual (pengguna menutup dialog). Mencatat jenis operasi beserta kesalahannya adalah hal yang mengubah NotAllowedError umum menjadi kelompok yang dapat ditindaklanjuti.
• Konteks minimum apa yang membuat kesalahan dapat di-debug? Tangkap error.name, jenis operasi, waktu terjadinya kesalahan dari awal operasi, tipe alur, apakah UI QR/hibrida ditampilkan, OS/browser/perangkat (termasuk versi), id korelasi (auth_flow_id) dan penolakan verifikasi server sebagai kode eksplisit.

Dua aturan praktis yang berlaku untuk semua jenis kesalahan: jangan pernah menunjukkan kesalahan peramban mentah kepada pengguna - selalu berikan alur alternatif yang jelas - dan pisahkan percobaan lokal dari percobaan QR/hibrida lintas perangkat, karena mereka gagal karena alasan yang berbeda dan memerlukan perbaikan yang berbeda. Pada skala besar, memelihara klasifikasi kesalahan di seluruh peramban, versi OS, dan pengelola kredensial adalah pekerjaan yang berkelanjutan. Pertimbangkan untuk menggunakan SDK observabilitas dengan pustaka pola yang dipelihara daripada membangunnya dari awal.

Tentang Corbado

Corbado adalah Authentication Intelligence Platform untuk tim CIAM yang menjalankan autentikasi consumer dalam skala besar. Kami membantu Anda melihat apa yang tidak bisa ditunjukkan oleh log IDP dan tool analytics generik: device, versi OS, browser, dan credential manager mana yang mendukung passkey; mengapa enrollment tidak menjadi login; di mana flow WebAuthn gagal; dan kapan update OS atau browser diam-diam merusak login — semuanya tanpa mengganti Okta, Auth0, Ping, Cognito, atau IDP internal Anda. Dua produk: Corbado Observe menambah observability untuk passkey dan metode login lainnya. Corbado Connect menghadirkan managed passkey dengan analytics terintegrasi (berdampingan dengan IDP Anda). VicRoads menjalankan passkey untuk 5M+ pengguna dengan Corbado (aktivasi passkey +80%). Bicara dengan pakar Passkey →

Di web, peramban menyatukan kedua kasus tersebut menjadi NotAllowedError demi alasan privasi, jadi Anda tidak dapat membedakannya secara langsung. Gunakan waktu sebagai proksi: kesalahan di bawah 1 detik biasanya berarti penolakan lingkungan atau hilangnya kemampuan, sedangkan 1-15 detik menunjukkan bahwa pengguna melihat dan mengabaikan dialog. Di aplikasi asli iOS dan Android, pengaturan preferImmediatelyAvailableCredentials sebelum permintaan memberi Anda sinyal "tidak ada kredensial" yang jelas (iOS kode 1005, Android GetCredentialRequest) sebelum UI apa pun ditampilkan.

Dalam pengerahan kunci sandi skala besar yang dioptimalkan, lebih dari 95% kesalahan WebAuthn yang tercatat adalah pembatalan pengguna yang wajar, bukan kegagalan sistem. Melacak jumlah error.name mentah tanpa memisahkan "pengguna menutup prompt" dari kegagalan sungguhan akan melambungkan metrik kesalahan dan menutupi kemunduran sesungguhnya yang tersembunyi di dalam banyaknya NotAllowedError. Pisahkan perhitungan Anda berdasarkan jenis operasi dan perlakukan keranjang yang dibatalkan oleh pengguna terpisah dari kesalahan yang tak terduga seperti SecurityError, ConstraintError serta DataError.

Kode iOS 1005 (NotInteractive) berarti tidak ada kunci sandi yang tersedia pada perangkat saat preferImmediatelyAvailableCredentials diatur pada ASAuthorizationController, dan tak satu pun UI ditampilkan kepada pengguna. Ini merupakan tanda bersih bahwa "kunci sandi tak terdeteksi keberadaannya di perangkat ini", sesuatu yang browser web gagal berikan karena hambatan privasi. Biasakan mengklasifikasikannya berdasarkan kode numerik, bukan pada localizedDescription, sebab seluruh rangkaian pesan dari Apple diterjemahkan ke tak kurang dari 30 bahasa dan tak jarang mengalami perombakan antar rilis OS.

Selama pembuatan bersyarat, NotAllowedError, AbortError dan InvalidStateError merupakan hasil yang diharapkan dan harus diabaikan tanpa menimbulkan gangguan, alih-alih diperlihatkan sebagai ralat. NotAllowedError menandakan bahwa fitur isi otomatis (autofill) tak tersedia atau tab halaman telah ditinggalkan, sementara InvalidStateError memberitahukan bahwasanya kunci sandi telah tersedia di penyedia. Sebelum memanggil fungsi tersebut, pakailah getClientCapabilities() dalam memastikan kompatibilitas conditionalCreate dan pantau visibilitas dokumen di halaman demi mencegah penggelembungan hitungan galat (error) Anda.

Catat jenis operasional (UI bersyarat, log masuk berbasis modal, pembuatan cara usang, atau penciptaan bersyarat beserta perlekatan otomatisnya), waktu sejak mulai terpicu sampai ralat mengemuka, tipe OS, rupa sistem perambah (browser), varian perangkat (mesinnya), keterlihatan bentuk UI-nya, berikut rujukan keterkaitan (correlation ID) penyambung notifikasi ralat dari pangkalan datanya. Penolakan dari pihak belakang penyaji (seperti selisih angka kode dan tak samanya rujukan nama log, plus ketiadaan kata-kuncinya di brankas) wajib tertuang melalui susunan struktur dengan baik, tanpa dicampur dengan kumpulan galat yang datangnya dari pihak gawai DOMException. Elemen-elemen itu jika dihimpun mampu mengarahkan hampir semua tipe kepalsuan hingga tertampung rapi dalam ember-ember solusinya, bukan cuma diterka-terka acak.