UX kesalahan aturan database: ubah kegagalan menjadi pesan yang jelas

Mengapa kegagalan constraint terasa buruk bagi pengguna

Saat seseorang mengetuk Simpan, mereka mengharapkan salah satu dari dua hasil: berhasil, atau mereka bisa cepat memperbaiki apa yang salah. Terlalu sering mereka mendapat banner umum seperti “Request failed” atau “Something went wrong.” Formulir tetap sama, tidak ada yang disorot, dan mereka hanya menebak-nebak.

Kesenjangan itulah mengapa UX untuk kesalahan constraint database penting. Database menegakkan aturan yang tidak pernah dilihat pengguna: “nilai ini harus unik,” “record ini harus merujuk ke item yang ada,” “field ini tidak boleh kosong.” Jika aplikasi menyembunyikan aturan itu di balik error yang samar, orang akan merasa disalahkan untuk masalah yang tidak mereka mengerti.

Error generik juga merusak kepercayaan. Orang menganggap aplikasi tidak stabil, jadi mereka mencoba lagi, me-refresh, atau meninggalkan tugas. Di lingkungan kerja, mereka mengirim pesan ke support dengan screenshot yang tidak membantu, karena screenshot itu tidak berisi detail berguna.

Contoh umum: seseorang membuat record customer dan mendapat “Save failed.” Mereka mencoba lagi dengan email yang sama. Gagal lagi. Sekarang mereka bertanya-tanya apakah sistem menduplikasi data, kehilangan data, atau keduanya.

Database sering menjadi sumber kebenaran terakhir, bahkan ketika Anda memvalidasi di UI. Database melihat keadaan terbaru, termasuk perubahan dari pengguna lain, job latar, dan integrasi. Jadi kegagalan constraint akan terjadi, dan itu normal.

Hasil yang baik sederhana: ubah aturan database menjadi pesan yang menunjuk ke field spesifik dan langkah selanjutnya. Misalnya:

• “Email sudah digunakan. Coba email lain atau masuk.”
• “Pilih akun yang valid. Akun yang dipilih tidak lagi ada.”
• “Nomor telepon wajib diisi.”

Sisa artikel ini membahas cara melakukan terjemahan itu, sehingga kegagalan berubah menjadi pemulihan cepat, apakah Anda menulis stack sendiri atau membangun dengan tool seperti AppMaster.

Jenis constraint yang akan Anda temui (dan apa artinya)

Sebagian besar momen “request failed” berasal dari sekumpulan kecil aturan database. Jika Anda bisa menamai aturannya, biasanya Anda bisa mengubahnya menjadi pesan yang jelas pada field yang tepat.

Berikut tipe constraint umum dalam bahasa sederhana:

• Unique constraint: Nilai harus satu-satunya. Contoh tipikal adalah email, username, nomor faktur, atau external ID. Saat gagal, pengguna tidak “salah melakukan sesuatu,” mereka bertabrakan dengan data yang sudah ada.
• Foreign key constraint: Satu record menunjuk ke record lain yang harus ada (seperti order.customer_id). Gagal ketika yang direferensikan dihapus, tidak pernah ada, atau UI mengirim ID yang salah.
• NOT NULL constraint: Nilai wajib hilang di level database. Ini bisa terjadi meski formulir tampak lengkap (misalnya UI tidak mengirim field, atau API menimpa nilainya).
• Check constraint: Nilai berada di luar aturan yang diizinkan, seperti “quantity harus > 0,” “status harus salah satu dari nilai ini,” atau “diskon harus antara 0 dan 100.”

Bagian yang rumit adalah masalah dunia nyata yang sama bisa terlihat berbeda tergantung database dan tooling Anda. Postgres mungkin memberi nama constraint (berguna), sementara ORM mungkin membungkusnya dalam pengecualian generik (tidak membantu). Bahkan unique constraint yang sama bisa muncul sebagai “duplicate key,” “unique violation,” atau kode error vendor-spesifik.

Contoh praktis: seseorang mengedit customer di panel admin, menekan Simpan, dan mendapat kegagalan. Jika API bisa memberi tahu UI itu adalah unique constraint pada email, Anda bisa menampilkan “Email ini sudah digunakan” di bawah field Email alih-alih toast yang samar.

Perlakukan setiap tipe constraint sebagai petunjuk tentang apa yang bisa dilakukan pengguna selanjutnya: pilih nilai berbeda, pilih record terkait yang ada, atau isi field wajib yang hilang.

Apa yang harus dilakukan pesan tingkat-field yang baik

Kegagalan constraint database adalah kejadian teknis, tapi pengalaman harus terasa seperti panduan biasa. UX kesalahan constraint yang baik mengubah “ada yang rusak” menjadi “ini yang perlu diperbaiki,” tanpa membuat pengguna menebak.

Gunakan bahasa sederhana. Ganti kata-kata database seperti “unique index” atau “foreign key” dengan sesuatu yang manusiawi. “Email ini sudah digunakan” jauh lebih berguna daripada “duplicate key value violates unique constraint.”

Taruh pesan di tempat tindakan berada. Jika error jelas milik satu input, tempelkan ke field itu agar pengguna bisa memperbaikinya segera. Jika berhubungan dengan seluruh aksi (mis. “Anda tidak bisa menghapus ini karena digunakan di tempat lain”), tampilkan di level formulir dengan langkah selanjutnya yang jelas.

Spesifik mengalahkan sopan. Pesan yang membantu menjawab dua pertanyaan: apa yang harus diubah, dan mengapa ditolak. “Pilih username lain” lebih baik daripada “Username tidak valid.” “Pilih customer sebelum menyimpan” lebih baik daripada “Data hilang.”

Berhati-hatilah dengan detail sensitif. Kadang pesan yang paling “membantu” membocorkan informasi. Pada layar login atau reset kata sandi, mengatakan “Tidak ada akun untuk email ini” dapat membantu penyerang. Dalam kasus seperti itu, gunakan pesan yang lebih aman seperti “Jika ada akun yang cocok dengan email ini, Anda akan menerima pesan segera.”

Rencanakan juga untuk lebih dari satu masalah sekaligus. Satu Simpan dapat gagal pada beberapa constraint. UI Anda harus mampu menampilkan beberapa pesan field sekaligus, tanpa membuat layar berantakan.

Pesan tingkat-field yang kuat menggunakan kata-kata sederhana, menunjuk ke field yang tepat (atau jelas di level formulir), memberi tahu pengguna apa yang diubah, menghindari pengungkapan fakta pribadi tentang akun atau record, dan mendukung banyak error dalam satu respons.

Rancang kontrak error antara API dan UI

UX yang baik dimulai dengan kesepakatan: saat sesuatu gagal, API memberi tahu UI persis apa yang terjadi, dan UI menampilkannya dengan cara yang sama setiap kali. Tanpa kontrak itu, Anda kembali ke toast generik yang tidak membantu siapa pun.

Bentuk error yang praktis itu kecil tapi spesifik. Harus membawa kode error yang stabil, field (saat terikat ke satu input), pesan manusiawi, dan detail opsional untuk logging.

{
  "error": {
    "code": "UNIQUE_VIOLATION",
    "field": "email",
    "message": "That email is already in use.",
    "details": {
      "constraint": "users_email_key",
      "table": "users"
    }
  }
}

Kuncinya adalah kestabilan. Jangan memaparkan teks database mentah ke pengguna, dan jangan membuat UI parsing string error Postgres. Kode harus konsisten lintas platform (web, iOS, Android) dan endpoint.

Putuskan di muka bagaimana Anda merepresentasikan error tingkat-field vs error tingkat-formulir. Error field berarti satu input diblokir (set field, tampilkan pesan di bawah input). Error level-formulir berarti aksi tidak bisa diselesaikan walau field terlihat valid (biarkan field kosong, tampilkan pesan dekat tombol Simpan). Jika beberapa field bisa gagal sekaligus, kembalikan array error, masing-masing dengan field dan code.

Untuk menjaga rendering konsisten, buat aturan UI yang membosankan dan dapat diprediksi: tampilkan error pertama sebagai ringkasan singkat di atas dan inline di samping field, jaga pesan singkat dan bisa ditindaklanjuti, pakai kata-kata yang sama lintas flow (signup, edit profil, layar admin), dan log details sambil hanya menampilkan message.

Jika Anda membangun dengan AppMaster, perlakukan kontrak ini seperti output API lainnya. Backend Anda bisa mengembalikan bentuk terstruktur, dan web (Vue3) serta aplikasi mobile yang dihasilkan bisa merendernya dengan satu pola bersama, sehingga setiap kegagalan constraint terasa seperti panduan, bukan crash.

Langkah demi langkah: terjemahkan error DB ke pesan field

UX kesalahan constraint database yang baik dimulai dengan memperlakukan database sebagai hakim akhir, bukan garis depan. Pengguna tidak boleh melihat teks SQL mentah, stack trace, atau “request failed” yang samar. Mereka harus melihat field mana yang perlu diperbaiki dan apa langkah selanjutnya.

Alur praktis yang bekerja di banyak stack:

1. Tentukan di mana error ditangkap. Pilih satu tempat di mana error database menjadi respons API (sering di lapisan repository/DAO atau handler error global). Ini mencegah kebingungan “kadang inline, kadang toast”.
2. Klasifikasikan kegagalan. Ketika write gagal, deteksi kelasnya: unique constraint, foreign key, NOT NULL, atau check constraint. Gunakan kode error driver bila memungkinkan. Hindari parsing teks manusia kecuali benar-benar tidak ada pilihan.
3. Peta nama constraint ke field formulir. Constraint adalah pengenal yang bagus, tapi UI butuh kunci field. Simpan lookup sederhana seperti users_email_key -> email atau orders_customer_id_fkey -> customerId. Taruh di dekat kode yang punya skema.
4. Buat pesan yang aman. Bangun teks singkat dan ramah pengguna berdasarkan kelas, bukan pesan DB mentah. Unique -> “Nilai ini sudah digunakan.” FK -> “Pilih customer yang ada.” NOT NULL -> “Field ini wajib diisi.” Check -> “Nilai berada di luar jangkauan yang diperbolehkan.”
5. Kembalikan error terstruktur dan render inline. Kirim payload konsisten (misalnya: [{ field, code, message }]). Di UI, lampirkan pesan ke field, scroll dan fokus ke field pertama yang gagal, dan biarkan banner global hanya sebagai ringkasan bila perlu.

Jika Anda membangun dengan AppMaster, terapkan ide yang sama: tangkap error database di satu tempat backend, terjemahkan menjadi format error field yang dapat diprediksi, lalu tampilkan di samping input di UI web atau mobile Anda. Ini menjaga pengalaman konsisten meski model data berubah.

Contoh realistis: tiga Simpan gagal, tiga hasil yang membantu

Kegagalan ini sering disatukan menjadi satu toast generik. Masing‑masing butuh pesan berbeda, meski semuanya berasal dari database.

1) Signup: email sudah terdaftar (unique constraint)

Kegagalan mentah (yang mungkin Anda lihat di log): duplicate key value violates unique constraint "users_email_key"

Yang harus dilihat pengguna: “Email itu sudah terdaftar. Coba masuk, atau gunakan email lain.”

Letakkan pesan di samping field Email dan biarkan formulir tetap terisi. Jika mungkin, tawarkan aksi sekunder seperti “Masuk,” agar mereka tidak menebak apa yang terjadi.

2) Buat pesanan: customer hilang (foreign key)

Kegagalan mentah: insert or update on table "orders" violates foreign key constraint "orders_customer_id_fkey"

Yang harus dilihat pengguna: “Pilih customer untuk membuat pesanan ini.”

Ini tidak terasa seperti “error” bagi pengguna. Ini terasa seperti konteks yang hilang. Sorot selector Customer, pertahankan item baris yang sudah mereka tambahkan, dan jika customer dihapus di tab lain, katakan begitu: “Customer itu tidak lagi ada. Pilih yang lain.”

3) Update profil: field wajib hilang (NOT NULL)

Kegagalan mentah: null value in column "last_name" violates not-null constraint

Yang harus dilihat pengguna: “Nama belakang wajib diisi.”

Itulah tampilan penanganan constraint yang baik: umpan balik formulir normal, bukan kegagalan sistem.

Untuk membantu tim support tanpa membocorkan detail teknis ke pengguna, simpan error lengkap di log (atau panel error internal): sertakan request ID dan user/session ID, nama constraint (jika ada) dan table/field, payload API (masking field sensitif), timestamp dan endpoint/aksi, serta pesan yang ditampilkan kepada pengguna.

Error foreign key: bantu pengguna pulih

Kegagalan foreign key biasanya berarti pengguna memilih sesuatu yang tidak lagi ada, tidak lagi diizinkan, atau tidak cocok dengan aturan kini. Tujuannya bukan hanya menjelaskan kegagalan, tapi memberi mereka langkah pemulihan yang jelas.

Seringkali, error foreign key dipetakan ke satu field: picker yang merujuk record lain (Customer, Project, Assignee). Pesan harus menyebut hal yang dikenali pengguna, bukan konsep database. Hindari ID internal atau nama table. “Customer tidak lagi ada” berguna. “FK_orders_customer_id violated (customer_id=42)” tidak.

Pola pemulihan yang baik memperlakukan error seperti pilihan yang kadaluarsa. Minta pengguna untuk memilih ulang dari daftar terbaru (refresh dropdown atau buka picker pencarian). Jika record dihapus atau diarsipkan, katakan itu dengan jelas dan arahkan ke alternatif aktif. Jika pengguna tidak punya akses, katakan “Anda tidak lagi punya izin untuk menggunakan item ini,” dan sarankan memilih yang lain atau menghubungi admin. Jika membuat record terkait adalah langkah normal berikutnya, tawarkan “Buat customer baru” alih-alih memaksa retry.

Record yang dihapus dan diarsipkan sering menjadi jebakan. Jika UI Anda bisa menampilkan item tidak aktif untuk konteks, beri label jelas (Arsip) dan cegah pemilihan. Itu mencegah kegagalan, tapi tetap menangani kasus ketika pengguna lain mengubah data.

Kadang error foreign key seharusnya berada di level formulir, bukan field. Lakukan itu ketika Anda tidak bisa andal menentukan referensi mana yang menyebabkan error, ketika beberapa referensi tidak valid, atau ketika masalah sebenarnya adalah izin di seluruh aksi.

NOT NULL dan validasi: cegah error, tapi tetap tangani

Kegagalan NOT NULL paling mudah dicegah dan paling menyebalkan ketika lolos. Jika seseorang melihat “request failed” setelah meninggalkan field wajib kosong, database melakukan pekerjaan UI. UX yang baik berarti UI mencegah kasus jelas, dan API tetap mengembalikan error field yang jelas saat sesuatu terlewat.

Mulai dengan pemeriksaan awal di formulir. Tandai field wajib dekat input, bukan hanya di banner umum. Petunjuk singkat seperti “Diperlukan untuk kuitansi” lebih membantu daripada bintang merah saja. Jika field bersifat kondisional (mis. “Nama perusahaan” hanya saat “Tipe akun = Bisnis”), tunjukkan aturan itu saat relevan.

Validasi UI tidak cukup. Pengguna bisa melewatinya dengan versi app lama, jaringan fluktuatif, retry massal, atau automasi. Cerminkan aturan yang sama di API sehingga Anda tidak membuang satu putaran hanya untuk gagal di database.

Jaga konsistensi istilah di seluruh aplikasi agar orang belajar arti tiap pesan. Untuk nilai yang hilang, gunakan “Wajib diisi.” Untuk batas panjang, gunakan “Terlalu panjang (maks 50 karakter).” Untuk format, gunakan “Format tidak valid (gunakan [email protected]).” Untuk tipe, gunakan “Harus berupa angka.”

Partial update membuat NOT NULL menjadi rumit. PATCH yang menghilangkan field wajib seharusnya tidak gagal jika nilai lama sudah ada, tapi harus gagal jika klien secara eksplisit mengatur menjadi null atau kosong. Tentukan aturan ini sekali, dokumentasikan, dan terapkan secara konsisten.

Pendekatan praktis: validasi pada tiga lapis: aturan formulir klien, validasi request API, dan jaring pengaman terakhir yang menangkap error NOT NULL database dan memetakan ke field yang benar.

Kesalahan umum yang kembali ke “request failed”

Cara tercepat merusak penanganan constraint adalah melakukan semua kerja berat di database, lalu menyembunyikan hasilnya di balik toast generik. Pengguna tidak peduli constraint men-trigger; mereka peduli apa yang harus diperbaiki, di mana, dan apakah data mereka aman.

Salah satu kekeliruan umum adalah menampilkan teks database mentah. Pesan seperti duplicate key value violates unique constraint terasa seperti crash, meski aplikasi bisa pulih. Mereka juga membuat tiket support karena pengguna menyalin teks yang menakutkan alih-alih memperbaiki satu field.

Perangkap lain adalah mengandalkan pencocokan string. Itu bekerja sampai Anda mengganti driver, meng-upgrade Postgres, atau mengganti nama constraint. Lalu pemetaan “email sudah digunakan” berhenti tanpa disadari, dan Anda kembali ke “request failed.” Pilih kode error stabil dan sertakan nama field yang dimengerti UI.

Perubahan skema merusak pemetaan field lebih sering daripada orang kira. Pergantian nama dari email ke primary_email bisa mengubah pesan jelas menjadi data tanpa tempat tampil. Jadikan pemetaan bagian dari perubahan yang sama dengan migrasi, dan buat test yang gagal keras jika kunci field tidak dikenal.

Pembunuh UX besar adalah mengubah setiap kegagalan constraint menjadi HTTP 500 tanpa body. Itu memberi tahu UI “ini kesalahan server,” sehingga tidak bisa menampilkan petunjuk field. Sebagian besar kegagalan constraint bisa diperbaiki pengguna, jadi kembalikan respons bergaya validasi dengan detail.

Beberapa pola yang perlu diwaspadai:

• Pesan email unik yang mengonfirmasi keberadaan akun (pakai kata-kata netral di alur pendaftaran)
• Menangani “satu error pada satu waktu” dan menyembunyikan field kedua yang rusak
• Form multi-langkah yang kehilangan error setelah klik kembali/lanjut
• Retry yang mengirimkan nilai kadaluarsa dan menimpa pesan field yang benar
• Logging yang menghilangkan nama constraint atau kode error, membuat bug sulit dilacak

Contoh: jika formulir pendaftaran mengatakan “Email sudah ada,” Anda mungkin membocorkan keberadaan akun. Pesan yang lebih aman adalah “Periksa email Anda atau coba masuk,” sambil tetap menempelkan error ke field email.

Daftar periksa cepat sebelum rilis

Sebelum rilis, periksa detail kecil yang menentukan apakah kegagalan constraint terasa seperti dorongan yang membantu atau jalan buntu.

Respons API: apakah UI benar-benar bisa bertindak?

Pastikan setiap kegagalan bergaya validasi mengembalikan struktur yang cukup untuk menunjuk ke input spesifik. Untuk tiap error, kembalikan field, code stabil, dan message manusiawi. Tutupi kasus database umum (unique, foreign key, NOT NULL, check). Simpan detail teknis untuk log, bukan untuk pengguna.

Perilaku UI: apakah membantu pengguna pulih?

Bahkan pesan sempurna terasa buruk jika formulir melawan pengguna. Fokuskan field pertama yang gagal dan scroll agar terlihat bila perlu. Pertahankan apa yang sudah diketik pengguna (terutama setelah error multi-field). Tampilkan error di tingkat field dulu, dengan ringkasan singkat hanya bila berguna.

Logging dan test: apakah Anda menangkap regresi?

Penanganan constraint sering rusak diam-diam saat skema berubah, jadi perlakukan ini sebagai fitur yang dipelihara. Log error DB secara internal (nama constraint, table, operasi, request ID), tapi jangan pernah menampilkannya langsung. Tambahkan test untuk setidaknya satu contoh tiap tipe constraint, dan verifikasi pemetaan Anda tetap stabil meski wording database berubah.

Langkah selanjutnya: buat ini konsisten di seluruh aplikasi

Sebagian besar tim memperbaiki error constraint satu layar pada satu waktu. Itu membantu, tapi pengguna melihat celah: satu formulir menampilkan pesan jelas, yang lain masih mengatakan “request failed.” Konsistensi yang membuat ini jadi pola, bukan tambal sulam.

Mulai dari tempat yang terasa paling menyusahkan. Ambil log atau tiket support seminggu terakhir dan pilih beberapa constraint yang muncul berulang. “Pelaku utama” itu harus dulu mendapat pesan ramah di tingkat-field.

Perlakukan terjemahan error seperti fitur produk kecil. Simpan satu pemetaan bersama yang digunakan seluruh aplikasi: nama constraint (atau kode) -> nama field -> pesan -> petunjuk pemulihan. Jaga pesan sederhana, dan buat petunjuknya bisa ditindaklanjuti.

Rencana rollout ringan yang cocok untuk siklus produk sibuk:

• Identifikasi 5 constraint yang paling sering ditemui pengguna dan tulis pesan yang ingin ditampilkan.
• Tambahkan tabel pemetaan dan gunakan di setiap endpoint yang menyimpan data.
• Standarisasi cara formulir merender error (penempatan sama, nada sama, perilaku fokus sama).
• Tinjau pesan dengan rekan non-teknis dan tanyakan: “Apa yang akan Anda lakukan selanjutnya?”
• Tambah satu test per formulir yang memeriksa field yang tepat disorot dan pesannya mudah dibaca.

Jika Anda ingin membangun perilaku konsisten ini tanpa menulis tiap layar, AppMaster (appmaster.io) mendukung API backend plus aplikasi web dan native yang dihasilkan. Itu memudahkan menggunakan satu format error terstruktur di semua klien, sehingga feedback tingkat-field tetap konsisten saat model data berubah.

Tulis catatan gaya pesan error singkat untuk tim Anda juga. Buat sederhana: kata-kata yang dihindari (istilah database), dan apa yang harus disertakan tiap pesan (apa yang terjadi, apa yang harus dilakukan selanjutnya).