Wawancara Product Manager: Bagaimana Cara Anda Merancang Pengalaman Error API yang Dapat Ditindaklanjuti?

1. Pertanyaan

Sebuah API data B2B melayani ribuan tim pengembang. Setelah suatu rilis, tiket dukungan semakin banyak yang menyatakan bahwa permintaan gagal tanpa menjelaskan cara memperbaikinya. Tim rekayasa (engineering) ingin mengekspos lebih banyak log internal, sementara tim penjualan meminta teks error kustom untuk setiap pelanggan. Sebagai product manager, rancang pengalaman error API yang dapat ditindaklanjuti tanpa merusak klien yang sudah ada.

2. Batasan dan klarifikasi

Pisahkan kegagalan input klien, autentikasi dan otorisasi, pembatasan laju (rate-limit), dependensi, dan layanan internal; jangan menyatukan semua kegagalan menjadi satu kode 500.
Buat respons dapat melayani penanganan mesin, diagnosis pengembang, dan presentasi pengguna akhir tanpa mencampuradukkan kebutuhan ketiganya.
SDK dan format log yang ada tidak dapat diubah semuanya secara langsung, sehingga rencana harus mendukung klien lama dan migrasi bertahap.
Jangan pernah mengembalikan jejak tumpukan (stack trace) yang sensitif, token, data pengguna, atau topologi internal secara langsung kepada pemanggil.

3. Kerangka kerja diagnosis produk

Bagi masalah menjadi tiga pertanyaan: apa yang terjadi, siapa yang dapat memperbaikinya, dan apa yang harus terjadi selanjutnya. Respons error memerlukan kode yang stabil dan dapat dibaca mesin, ringkasan yang aman untuk manusia, detail terstruktur opsional, dan ID korelasi dukungan; dokumentasi dan SDK memetakan kode tersebut ke sebuah solusi. Analisis produk harus melacak tingkat pemulihan setelah error, percobaan ulang (retry) berulang, waktu dari kegagalan hingga keberhasilan, tiket dukungan berdasarkan kelas error, dan distribusi versi, bukan hanya tingkat kegagalan total.

4. Solusi referensi

text

errorResponse:
  status: canonicalStatusCode
  code: stableProductErrorCode
  message: safeHumanSummary
  details:
    reason: machineActionableReason
    fieldViolations: optionalFieldErrors
    retryAfter: optionalDelay
  requestId: supportCorrelationId
  docsUrl: versionedFixGuide

clientFlow(error):
  classify(error.status, error.code)
  if retryable: backoffAndRetry(error.details.retryAfter)
  else if fieldError: highlightFields(error.details.fieldViolations)
  else: showDocsAndRequestId(error.docsUrl, error.requestId)

Tentukan sekumpulan kecil kode status kanonikal yang stabil, lalu gunakan kode error produk untuk penyebab yang dapat ditindaklanjuti. Tempatkan pelanggaran bidang (field violations), waktu percobaan ulang, dan tautan dokumentasi dalam detail terstruktur. Konsol menampilkan langkah-langkah perbaikan berdasarkan kode, sementara SDK memetakan error ke tipe yang dapat ditangkap (catchable) dan mempertahankan kode aslinya. Layanan mencatat diagnostik lengkap secara internal tetapi hanya mengembalikan ringkasan yang aman dan ID korelasi.

5. Pertukaran (trade-off) dan strategi peluncuran

Kode error yang lebih terperinci membuat panduan lebih presisi tetapi meningkatkan biaya kompatibilitas dan dokumentasi. Mulailah dengan error bervolume tinggi yang dapat diperbaiki pengembang, lalu tambahkan detail untuk kelas yang lebih kecil; jangan membuat protokol kustom per penyewa (tenant). Bidang baru harus kompatibel ke belakang (backward compatible). Setelah arti suatu kode dipublikasikan, jaga agar tetap stabil: klien lama terus menerima format lama sementara SDK yang lebih baru memilih untuk menggunakan detail terstruktur. Respons kegagalan parsial (partial-failure) perlu diwaspadai karena menambah percabangan logika pada klien; perkenalkan hanya ketika API batch memiliki kebutuhan yang jelas.

6. Verifikasi dan observabilitas

Ambil sampel tiket dukungan dan log panggilan, beri label pada setiap kegagalan apakah dapat didiagnosis, dapat diperbaiki, dan dicoba ulang tanpa perlu atau tidak.
Tulis pengujian kontrak untuk autentikasi, validasi bidang, batas laju, batas waktu dependensi, dan kegagalan yang tidak diketahui, dengan memeriksa status, kode, dan URL dokumentasi.
Luncurkan format baru secara bertahap dan bandingkan tingkat pemulihan, percobaan ulang berulang, volume tiket, dan tingkat penangkapan pengecualian oleh SDK.
Pantau kode yang tidak dikenal, pangsa klien lama, konversi klik dokumentasi menjadi berhasil, dan kebocoran bidang sensitif dalam respons error.

7. Kesalahan umum

Mengekspos lebih banyak log atau stack trace tanpa memberikan kode yang stabil dan tindakan perbaikan kepada pemanggil.
Mengodekan semua makna bisnis ke dalam status HTTP sehingga klien harus mem-parsing string.
Memasukkan pengecualian internal, token, atau parameter permintaan lengkap ke dalam pesan yang dianggap ramah pengguna.
Mengganti nama atau menghapus kode dalam satu rilis dan merusak SDK lama selama pembaruan.

8. Poin penilaian wawancara

Mengklasifikasikan error berdasarkan tanggung jawab perbaikan

Kandidat harus memisahkan kegagalan input, izin, batas laju, dependensi, dan internal, serta menyatakan tindakan pemanggil dan tanggung jawab layanan untuk masing-masingnya.

Merancang model error yang stabil dan aman

Jawaban harus mencakup kode yang dapat dibaca mesin, ringkasan yang aman, detail terstruktur, ID korelasi, dan dokumentasi berversi tanpa mengekspos bagian internal.

Menghubungkan pengalaman dengan metrik produk

Kandidat harus menggunakan tingkat pemulihan, percobaan ulang berulang, waktu perbaikan, tiket, dan distribusi versi daripada hanya mengandalkan tingkat kegagalan semata.

Merencanakan migrasi yang kompatibel

Kandidat harus menjelaskan kompatibilitas format lama, adopsi SDK secara bertahap, kriteria peluncuran dan pembatalan (rollback), serta kapan sebaiknya tidak memperkenalkan protokol kegagalan parsial yang kompleks.

Wawancara Product Manager: Bagaimana Cara Anda Merancang Pengalaman Error API yang Dapat Ditindaklanjuti?

Pertanyaan