karawaci.kode

2026-10-19 · 11 min

Format Error Response API yang Manusiawi: RFC 9457 dan Psikologinya

Hampir semua diskusi soal format error response API yang saya ikuti berhenti di pertanyaan teknis: pakai kode HTTP apa, field-nya apa saja, perlu errorCode atau tidak. Pertanyaan itu penting. Tapi sebagai orang yang sehari-hari mempelajari perilaku konsumen, saya selalu ingin menambahkan satu pertanyaan lagi: apa yang dirasakan orang yang membaca pesan itu?

Pesan error muncul tepat di momen ketika user paling cemas. Mereka sedang mencoba membayar, mendaftar, atau menyimpan sesuatu yang sudah mereka isi lima menit, lalu sistem berkata “tidak”. Di titik itu, satu kalimat pendek menentukan apakah mereka mencoba lagi atau menutup aplikasi. Klaim saya sederhana: copy error yang menyalahkan user, atau yang terlalu samar untuk ditindaklanjuti, membuat orang berhenti mencoba.

Artikel ini ditulis untuk backend developer yang sedang mendesain kontrak error. Saya akan memakai dua konsep psikologi yang sudah mapan, memetakannya ke struktur RFC 9457 Problem Details, lalu memberi tabel before/after pesan error dalam Bahasa Indonesia yang bisa langsung Anda curi.

Satu catatan kejujuran di awal: Anda mungkin pernah melihat angka seperti “sekian persen user meninggalkan form karena pesan error”. Banyak angka semacam itu beredar tanpa sumber yang bisa saya telusuri, jadi saya tidak akan memuatnya di sini. Argumen di artikel ini berdiri di atas konsep, bukan di atas statistik.

Dua Konsep Psikologi yang Relevan untuk Pesan Error

Atribusi: siapa yang disalahkan?

Teori atribusi, yang berakar dari karya Fritz Heider dan kemudian dikembangkan Bernard Weiner, mempelajari cara orang menjelaskan penyebab suatu kejadian. Ketika sesuatu gagal, kita otomatis bertanya “ini salah siapa?” dan “apakah ini bisa diperbaiki?”. Weiner membedakan beberapa dimensi penjelasan, tiga di antaranya sangat berguna untuk menulis pesan error:

  • Lokus (internal atau eksternal). Apakah penyebabnya ada di diri saya, atau di luar saya?
  • Stabilitas (menetap atau sementara). Apakah ini akan terus terjadi, atau hanya kali ini?
  • Kendali (bisa dikendalikan atau tidak). Apakah ada yang bisa saya lakukan?

Sekarang baca pesan “Input Anda tidak valid” dengan kacamata itu. Lokusnya internal (“Anda”), stabilitasnya tidak jelas, dan kendalinya nol karena tidak ada petunjuk apa yang harus diubah. Itu kombinasi paling buruk: user merasa bersalah tapi tidak tahu harus berbuat apa.

Bandingkan dengan “Nomor HP perlu 10–13 digit, diawali 08”. Pesan ini tidak menunjuk siapa pun. Ia menyebut aturan, dan aturan itu langsung memberi kendali. User tahu persis apa yang harus diketik.

Learned helplessness: error yang samar dan berulang

Konsep learned helplessness berasal dari eksperimen Martin Seligman dan Steven Maier di akhir 1960-an. Intinya: ketika usaha berulang kali tidak berpengaruh pada hasil, individu cenderung berhenti mencoba, bahkan ketika situasinya sebenarnya sudah bisa diatasi. Reformulasi teori ini oleh Abramson, Seligman, dan Teasdale pada 1978 menghubungkannya langsung dengan atribusi: rasa tidak berdaya paling kuat ketika penyebab kegagalan dianggap internal, menetap, dan berlaku di mana-mana.

Saya perlu jujur soal batasnya. Riset aslinya dilakukan di laboratorium dan konteks klinis, bukan di layar checkout. Saya memakainya sebagai lensa, bukan sebagai bukti empiris tentang UI. Tapi polanya mudah dikenali oleh siapa pun yang pernah melihat rekaman sesi user: tekan “Simpan”, muncul “Terjadi kesalahan”, tekan lagi, muncul pesan yang sama, tekan sekali lagi, lalu tab ditutup. Tiga kali mencoba tanpa informasi baru sudah cukup untuk mengajarkan bahwa usaha tidak ada gunanya.

Jadi tugas pesan error, dari sudut pandang psikologi, ada tiga:

  1. Letakkan penyebab secara jujur. Kalau sistem yang gagal, katakan sistem yang gagal. Kalau isian perlu diubah, sebut aturannya tanpa menuding.
  2. Beri sinyal bahwa ini sementara dan spesifik. Satu field, satu aturan, satu kejadian.
  3. Kembalikan kendali. Selalu ada langkah berikutnya.

Kabar baiknya untuk backend developer: ketiga hal ini bisa dirancang dari struktur response, bukan cuma dari kata-kata.

RFC 9457 Problem Details: Format Error Response API yang Memisahkan Mesin dan Manusia

RFC 9457, Problem Details for HTTP APIs, terbit Juli 2023 dan menggantikan RFC 7807. Ia mendefinisikan objek JSON standar untuk error HTTP dengan media type application/problem+json. Yang membuat saya menyukai standar ini bukan detail teknisnya, melainkan pembagian perannya: ada field yang ditujukan untuk kode, dan ada field yang ditujukan untuk manusia.

FieldUntuk siapaFungsiCatatan penting dari RFC
typeMesinURI yang mengidentifikasi jenis masalahKalau tidak diisi, dianggap about:blank. Sebaiknya mengarah ke dokumentasi yang bisa dibaca developer
statusMesinKode status HTTPHanya bersifat informatif; nilainya harus sama dengan status HTTP response sebenarnya
instanceMesin (dan support)URI untuk kejadian spesifik iniBerguna sebagai ID korelasi ke log
titleManusiaRingkasan singkat jenis masalahTidak boleh berubah antar kejadian, kecuali untuk lokalisasi
detailManusiaPenjelasan untuk kejadian iniRFC menyarankan detail fokus membantu client memperbaiki masalah, bukan berisi info debugging

Dua kalimat dari RFC 9457 sebaiknya ditempel di dinding tim Anda. Pertama, detail sebaiknya fokus membantu client memperbaiki masalah, bukan memberi informasi debugging. Itu persis prinsip “kembalikan kendali”. Kedua, client tidak seharusnya mem-parse detail untuk mengambil informasi. Kalau ada data yang perlu dibaca mesin, taruh di extension member. Pemisahan ini yang membuat copy bisa diperbaiki tanpa merusak kode.

Contoh response untuk satu masalah bisnis:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: id

{
  "type": "https://api.example.com/problems/saldo-tidak-cukup",
  "title": "Saldo tidak cukup",
  "status": 403,
  "detail": "Saldo Anda Rp45.000, total pembayaran Rp60.000. Isi saldo minimal Rp15.000 atau pilih metode pembayaran lain.",
  "instance": "urn:uuid:3f8c2a41-7d0e-4b9a-9c61-2e5f0a8b1d47",
  "saldo": 45000,
  "total": 60000
}

Perhatikan cara detail bekerja secara psikologis. Ia menyebut fakta (angka saldo dan total), tidak menyalahkan, dan menawarkan dua jalan keluar. Sementara itu, saldo dan total tersedia sebagai angka sehingga frontend bisa membuat tombol “Isi saldo Rp15.000” tanpa mem-parse kalimat.

Error Validasi per Field dengan Extension Member

Form adalah tempat error paling sering muncul, dan biasanya ada lebih dari satu masalah sekaligus. RFC 9457 secara eksplisit membahas kasus ini: kalau beberapa masalah berjenis sama, gunakan satu problem type dan jabarkan tiap kejadian di extension member. Contoh di RFC sendiri memakai array errors yang berisi detail dan pointer (JSON Pointer ke bagian request yang bermasalah). Saya menambahkan code agar frontend punya kunci yang stabil.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: id

{
  "type": "https://api.example.com/problems/validasi",
  "title": "Ada isian yang perlu diperbaiki",
  "status": 422,
  "detail": "2 isian perlu diperbaiki sebelum data bisa disimpan.",
  "instance": "urn:uuid:9b1e6c3d-0a52-4f7e-8d2b-61c4e7a0f935",
  "errors": [
    {
      "pointer": "#/phone",
      "code": "phone.format",
      "detail": "Nomor HP perlu 10–13 digit, diawali 08."
    },
    {
      "pointer": "#/birthDate",
      "code": "birthDate.future",
      "detail": "Tanggal lahir tidak boleh setelah hari ini."
    }
  ]
}

Struktur ini menjawab ketiga kebutuhan psikologis tadi. Setiap masalah terikat ke satu field (spesifik, bukan global), tiap pesan menyebut aturan (bukan menyalahkan), dan semua masalah dikirim sekaligus. Poin terakhir sering diremehkan. Kalau server hanya mengembalikan error pertama, user memperbaiki satu field, menekan kirim, lalu disodori error baru. Dari sisi user, itu terasa seperti sistem yang terus berganti aturan, dan itulah resep paling cepat menuju rasa tidak berdaya.

Kalau Anda bertanya bagaimana dengan masalah yang jenisnya berbeda dalam satu request (misalnya validasi gagal dan akun dibekukan), RFC 9457 menyarankan mengembalikan masalah yang paling relevan atau paling mendesak. Akun yang dibekukan lebih mendesak; tidak ada gunanya meminta user membetulkan nomor HP kalau mereka toh tidak bisa melanjutkan.

Contoh Pesan Error yang Baik: Tabel Before/After

Ini bagian yang paling sering ditanyakan ke saya. Kolom “Sesudah” adalah usulan copy dalam Bahasa Indonesia; sesuaikan angkanya dengan aturan bisnis Anda.

SituasiSebelumSesudahKenapa lebih baik
Format nomor HPInvalid inputNomor HP perlu 10–13 digit, diawali 08.Menyebut aturan, langsung bisa ditindaklanjuti
Field kosongField is requiredNama penerima belum diisi.Menyebut field mana, nada netral
Format emailEmail tidak validAlamat email belum lengkap. Contoh: [email protected]Memberi pola yang benar
Panjang kata sandiPassword invalidKata sandi minimal 8 karakter, saat ini baru 6.Memberi jarak ke target, terasa bisa dicapai
TanggalInvalid dateTanggal lahir tidak boleh setelah hari ini.Aturannya jelas tanpa istilah teknis
Ukuran file413 Payload Too LargeUkuran foto 8 MB, maksimal 5 MB. Kecilkan dulu atau pilih foto lain.Fakta + dua jalan keluar
Login gagalPassword salah!Email atau kata sandi belum cocok. Coba lagi, atau atur ulang kata sandi.Tidak menuding, tetap aman dari user enumeration
OTPAnda salah memasukkan kode OTPKode OTP belum cocok. Pastikan memakai kode dari SMS terbaru.Lokus netral, ada petunjuk konkret
Sesi habis401 UnauthorizedSesi Anda sudah berakhir. Masuk lagi untuk melanjutkan.Menjelaskan penyebab yang bukan salah user
Tidak punya akses403 ForbiddenAkun Anda belum punya akses ke laporan keuangan. Minta admin tim menambahkan akses ini.Memberi tahu siapa yang bisa membantu
Data tidak ada404 Not FoundPesanan INV-2041 tidak ditemukan. Cek lagi nomornya di email konfirmasi.Spesifik, mengarahkan ke sumber yang benar
Rate limitToo Many RequestsTerlalu banyak percobaan. Coba lagi dalam 2 menit.Menyatakan ini sementara, ada waktu yang jelas
Error serverTerjadi kesalahanAda gangguan di sistem kami, bukan karena isian Anda. Data belum tersimpan, coba lagi beberapa saat. Kode referensi: 3F8C2A41Atribusi eksternal yang jujur, status data jelas, ada jalur ke support
Layanan pihak ketiga lambatRequest timeoutLayanan pembayaran sedang lambat merespons. Saldo Anda belum terpotong. Coba lagi dalam beberapa menit.Meredakan kecemasan terbesar user: “uang saya ke mana?”

Dua baris terakhir butuh peringatan keras: tulis “data belum tersimpan” atau “saldo belum terpotong” hanya kalau backend benar-benar menjaminnya. Kalimat yang menenangkan tapi salah jauh lebih merusak kepercayaan daripada kalimat yang samar. Kalau Anda tidak tahu status transaksinya, katakan itu, lalu arahkan ke halaman riwayat transaksi untuk mengecek.

Perhatikan juga baris “Error server”. Banyak tim menulis pesan 5xx dengan nada yang sama seperti pesan validasi, sehingga user menyimpulkan mereka yang salah ketik. Mengatakan terus terang “ini gangguan di sistem kami” bukan soal sopan santun. Itu koreksi atribusi: user tidak perlu mengubah isian, mereka cukup menunggu atau mencoba lagi.

Tabel Pemetaan Kode Error ke Pesan

Supaya copy di atas konsisten di seluruh endpoint, simpan di satu tempat. Contoh berikut sengaja sederhana: sebuah kamus kode ke pesan, fungsi pembentuk Problem Details, dan validasi kecil.

// pesan-error.ts
export type FieldError = { pointer: string; code: string; detail: string };

export type Problem = {
  type: string;
  title: string;
  status: number;
  detail?: string;
  instance?: string;
  errors?: FieldError[];
};

// Satu sumber copy. Ubah kalimat di sini, bukan di tiap handler.
const PESAN_FIELD: Record<string, string> = {
  "phone.required": "Nomor HP belum diisi.",
  "phone.format": "Nomor HP perlu 10–13 digit, diawali 08.",
  "email.required": "Alamat email belum diisi.",
  "email.format": "Alamat email belum lengkap. Contoh: [email protected]",
  "birthDate.future": "Tanggal lahir tidak boleh setelah hari ini.",
};

const PESAN_CADANGAN = "Isian ini belum sesuai. Periksa lagi, ya.";

export function fieldError(pointer: string, code: string): FieldError {
  return { pointer, code, detail: PESAN_FIELD[code] ?? PESAN_CADANGAN };
}

export function validationProblem(instance: string, errors: FieldError[]): Problem {
  return {
    type: "https://api.example.com/problems/validasi",
    title: "Ada isian yang perlu diperbaiki",
    status: 422,
    detail: `${errors.length} isian perlu diperbaiki sebelum data bisa disimpan.`,
    instance,
    errors,
  };
}

const PHONE_RE = /^08\d{8,11}$/; // total 10–13 digit
const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export function validasiDaftar(body: {
  phone?: string;
  email?: string;
  birthDate?: string;
}): FieldError[] {
  // Kumpulkan SEMUA masalah, jangan berhenti di yang pertama.
  const errors: FieldError[] = [];

  if (!body.phone) errors.push(fieldError("#/phone", "phone.required"));
  else if (!PHONE_RE.test(body.phone)) errors.push(fieldError("#/phone", "phone.format"));

  if (!body.email) errors.push(fieldError("#/email", "email.required"));
  else if (!EMAIL_RE.test(body.email)) errors.push(fieldError("#/email", "email.format"));

  if (body.birthDate && new Date(body.birthDate) > new Date()) {
    errors.push(fieldError("#/birthDate", "birthDate.future"));
  }

  return errors;
}

Lalu di handler, misalnya dengan Express:

// server.ts — jalankan dengan: npx tsx server.ts
import express from "express";
import { randomUUID } from "node:crypto";
import { validasiDaftar, validationProblem } from "./pesan-error";

const app = express();
app.use(express.json());

app.post("/daftar", (req, res) => {
  const errors = validasiDaftar(req.body ?? {});

  if (errors.length > 0) {
    res
      .status(422)
      .type("application/problem+json")
      .json(validationProblem(`urn:uuid:${randomUUID()}`, errors));
    return;
  }

  res.status(201).json({ ok: true });
});

app.listen(3000, () => console.log("http://localhost:3000"));

Coba dengan curl -i -X POST localhost:3000/daftar -H 'Content-Type: application/json' -d '{"phone":"0812","email":"budi@"}'. Anda akan menerima status 422 dengan header Content-Type: application/problem+json dan dua entri di errors.

Validasi di atas memang minimal. Regex email-nya hanya menangkap kesalahan yang paling umum, dan untuk proyek nyata Anda mungkin memakai library validasi. Yang ingin saya tunjukkan adalah polanya: kode error stabil untuk mesin, kalimat di satu kamus untuk manusia.

Pedoman Copy untuk Frontend

Backend bisa menyediakan struktur yang baik, tapi yang dilihat user tetap layar frontend. Ini pedoman yang biasanya saya bagikan ke tim produk:

  1. Utamakan kamus copy milik frontend, pakai detail sebagai cadangan. Petakan dari type atau code. Kalau kodenya tidak dikenal, tampilkan detail. Kalau response bahkan bukan problem+json (misalnya halaman HTML 502 dari load balancer), tampilkan pesan gangguan sistem generik.
  2. Tampilkan error di dekat field-nya. Ubah pointer seperti #/phone menjadi nama input, lalu tampilkan pesan tepat di bawah input itu. Toast di pojok layar mudah terlewat. Hubungkan pesannya ke input dengan aria-describedby agar terbaca oleh screen reader.
  3. Jangan pernah mengosongkan isian setelah error. Menghapus apa yang sudah diketik user adalah hukuman. Satu-satunya pengecualian yang wajar adalah field kata sandi atau OTP.
  4. Sebut status data kalau Anda tahu pastinya. “Belum tersimpan”, “saldo belum terpotong”, “draf tetap aman”. Ketidakpastian soal uang dan data adalah sumber kecemasan terbesar.
  5. Bedakan nada error user dan error sistem. Error 4xx menyebut aturan. Error 5xx menyebut bahwa masalahnya ada di sistem dan menawarkan coba lagi.
  6. Hindari bahasa yang menuding dan mendramatisasi. Buang “Anda salah”, “ilegal”, “fatal”, “GAGAL” dengan huruf kapital, dan tanda seru. Ganti “salah” dengan “belum sesuai” atau “belum cocok”.
  7. Pilih satu istilah dan pakai terus. Kalau sudah memakai “kata sandi”, jangan berganti ke “password” atau “PIN” di layar lain. Istilah yang berubah-ubah membuat user ragu sedang mengisi apa.
  8. Beri kode referensi untuk error sistem. Potongan pendek dari instance sudah cukup. User merasa punya pegangan, dan tim support bisa langsung mencari log yang tepat.
  9. Batasi percobaan ulang yang sia-sia. Kalau error yang sama muncul dua kali berturut-turut, ubah pesannya: tawarkan jalur lain, seperti menghubungi support atau mencoba metode lain. Ini cara paling langsung memutus pola learned helplessness.

Yang Tidak Boleh Masuk ke Response

Bagian Security Considerations di RFC 9457 mengingatkan bahwa detail error bisa membocorkan informasi internal. Dari sisi psikologi pun, informasi teknis tidak membantu user mana pun. Jangan masukkan ke detail atau extension member:

  • stack trace, nama exception, atau pesan error mentah dari library;
  • query SQL, nama tabel, nama kolom database, atau hostname internal;
  • informasi yang memungkinkan user enumeration, seperti “email ini tidak terdaftar” di form login;
  • data pribadi milik orang lain.

Semua itu tempatnya di log server, dikaitkan dengan instance yang sama. Response untuk user cukup membawa kunci untuk menemukannya.

Dari Kontrak ke Implementasi

Artikel ini sengaja berhenti di kontrak dan copy. Untuk sisi kodenya, ada dua tulisan yang melengkapi:

  • Pola Error Handling TypeScript Modern 2026 membahas cara memodelkan error di domain dengan Result type dan discriminated union. Kode error yang stabil seperti phone.format sangat cocok menjadi varian union di sana, lalu baru diterjemahkan ke Problem Details di lapisan HTTP.
  • Error Boundaries and Retry Logic for a Production API Client membahas sisi client: error mana yang layak di-retry dan mana yang tidak. Ini berkaitan langsung dengan copy. Error 422 tidak boleh di-retry otomatis dan pesannya harus mengarahkan user mengubah isian, sementara 503 boleh di-retry dan pesannya boleh berbunyi “coba lagi beberapa saat”.

Penutup

Saat mendesain format error response API, kita sebenarnya sedang mendesain percakapan di momen paling tidak nyaman bagi user. RFC 9457 memberi kerangka yang rapi untuk itu: type, status, dan instance untuk mesin, title dan detail untuk manusia, serta extension member untuk detail per field. Psikologi memberi alasan kenapa pemisahan itu penting: orang yang tahu penyebabnya, tahu masalahnya sementara, dan tahu langkah berikutnya akan mencoba lagi.

Kalau Anda hanya sempat mengerjakan satu hal minggu ini, cari pesan “Terjadi kesalahan” dan “Invalid input” di codebase Anda, lalu tanyakan pada masing-masing: setelah membaca ini, apa yang bisa user lakukan? Kalau jawabannya “tidak ada”, pesan itu perlu ditulis ulang.

Ditulis oleh Tania Hartono