Layar laptop menampilkan kode JavaScript dengan penanganan error AJAX di meja kerja

Suatu sore, seorang pengembang menerima laporan dari pengguna: tombol simpan tidak merespons. Setelah diperiksa, request AJAX ke server ternyata gagal karena koneksi terputus, tetapi kode tidak memiliki penanganan error sama sekali. Akibatnya, halaman diam dan pengguna mengira tombolnya rusak.

Menangani error AJAX di jQuery berarti menyiapkan jalur alternatif ketika request gagal, sehingga aplikasi tetap memberi tahu pengguna apa yang terjadi dan tidak meninggalkan mereka di tengah jalan. Artikel ini membahas cara mendeteksi kegagalan, membedakan jenis error, dan menampilkan pesan yang berguna.

Mengapa error AJAX sering terlewat

Banyak contoh kode AJAX di internet hanya menampilkan callback sukses. Pola itu membuat pengembang fokus pada jalur bahagia dan lupa bahwa jaringan bisa putus, server bisa lambat, atau sesi pengguna bisa kedaluwarsa. Tanpa penanganan, kegagalan request hanya terlihat di konsol browser, sementara pengguna tidak mendapat informasi apa pun.

jQuery menyediakan beberapa titik untuk menangkap kegagalan. Anda bisa memakai callback error di objek pengaturan, method .fail() pada promise, atau pengaturan global $.ajaxSetup untuk menangani error yang tidak tertangani di tingkat request.

Struktur dasar penanganan error

Callback error menerima tiga argumen: jqXHR, textStatus, dan errorThrown. Ketiganya memberi petunjuk berbeda tentang penyebab kegagalan.

  • jqXHR: objek yang menyimpan status HTTP, responseText, dan header.
  • textStatus: status teks seperti "timeout", "error", "abort", atau "parsererror".
  • errorThrown: pesan tambahan dari server atau exception yang dilempar.

Contoh penggunaannya:

$.ajax({
  url: '/api/simpan',
  method: 'POST',
  data: { judul: 'Catatan' },
  success: function(res) {
    console.log('Berhasil', res);
  },
  error: function(jqXHR, textStatus, errorThrown) {
    console.log('Status:', textStatus);
    console.log('HTTP:', jqXHR.status);
    console.log('Pesan:', errorThrown);
  }
});

Dengan informasi ini, Anda bisa membedakan apakah masalahnya di jaringan, server, atau data yang dikirim.

Membedakan jenis kegagalan

Status HTTP memberi gambaran kasar tentang penyebab error. Kode 4xx biasanya berarti permintaan bermasalah dari sisi klien, misalnya token tidak valid atau parameter kurang. Kode 5xx menandakan server gagal memproses permintaan. Selain kode HTTP, textStatus bisa bernilai "timeout" jika request melewati batas waktu yang ditentukan, atau "parsererror" jika respons tidak bisa diurai sebagai JSON.

Menampilkan pesan generik untuk semua jenis error membuat pengguna bingung. Berikan pesan yang sesuai: “Koneksi terputus, coba lagi” untuk timeout, “Sesi Anda berakhir, silakan masuk kembali” untuk 401, dan “Terjadi kesalahan di server” untuk 500.

Menangani error dengan .fail()

Jika Anda memakai gaya promise, method .fail() bisa dirangkai setelah $.ajax() atau $.get(). Pendekatan ini membuat kode lebih rapi ketika ada beberapa langkah berurutan.

$.ajax({ url: '/api/data', dataType: 'json' })
  .done(function(data) {
    render(data);
  })
  .fail(function(jqXHR, textStatus) {
    if (textStatus === 'timeout') {
      tampilkanPesan('Koneksi lambat, coba lagi.');
    } else if (jqXHR.status === 404) {
      tampilkanPesan('Data tidak ditemukan.');
    } else {
      tampilkanPesan('Gagal memuat data.');
    }
  });

Perhatikan bahwa .fail() juga menangkap error yang terjadi di dalam .done() jika Anda melempar exception di sana. Ini bisa membantu, tetapi juga bisa menyembunyikan bug di kode render.

Timeout dan pembatalan request

Request yang menggantung tanpa batas waktu membuat antarmuka terasa macet. jQuery memungkinkan Anda menetapkan timeout dalam milidetik. Ketika waktu habis, callback error dipanggil dengan textStatus bernilai "timeout".

$.ajax({
  url: '/api/laporan',
  timeout: 5000,
  error: function(jqXHR, textStatus) {
    if (textStatus === 'timeout') {
      alert('Server tidak merespons dalam 5 detik.');
    }
  }
});

Anda juga bisa membatalkan request yang sedang berjalan dengan memanggil jqXHR.abort(). Ini berguna ketika pengguna berpindah halaman atau mengetik pencarian baru sebelum request sebelumnya selesai. Status yang diterima callback error adalah "abort", dan biasanya tidak perlu ditampilkan sebagai error ke pengguna.

Menampilkan pesan error yang berguna

Pesan error sebaiknya muncul di dekat elemen yang terlibat, bukan hanya di konsol. Untuk form, tampilkan pesan di bawah tombol simpan. Untuk daftar data, tampilkan baris placeholder dengan tombol “Coba lagi”.

Hindari menampilkan kode status mentah seperti “500 Internal Server Error” kepada pengguna umum. Simpan detail teknis di log, dan tampilkan kalimat yang menjelaskan langkah berikutnya. Jika aplikasi Anda memiliki banyak request, pertimbangkan untuk memusatkan penanganan error di satu fungsi agar pesan konsisten.

Tips debugging error AJAX

Ketika error sulit dilacak, periksa hal berikut secara berurutan:

  1. Buka tab Network di developer tools dan lihat status, header, serta respons mentah.
  2. Pastikan URL dan method sesuai dengan yang diharapkan server.
  3. Periksa apakah dataType cocok dengan format respons. Jika server mengirim HTML tetapi Anda meminta JSON, jQuery akan melaporkan parsererror.
  4. Untuk request POST, pastikan data terkirim dengan format yang benar, terutama jika server mengharapkan JSON.
  5. Gunakan console.log di callback error untuk melihat nilai jqXHR.status dan responseText.

Jika error hanya muncul di lingkungan produksi, periksa apakah ada perbedaan konfigurasi CORS, URL dasar, atau token autentikasi. Untuk pendekatan yang lebih terstruktur dalam menampilkan data setelah request berhasil, lihat panduan cara menampilkan data dari AJAX jQuery ke HTML.

Ringkasan

Menangani error AJAX di jQuery berarti menyiapkan callback error, memahami arti status HTTP dan textStatus, serta menampilkan pesan yang membantu pengguna mengambil tindakan. Dengan timeout, pembatalan request, dan pesan yang spesifik, aplikasi tetap terasa responsif meskipun ada gangguan jaringan atau masalah server.

Pertanyaan yang Sering Diajukan

Apa perbedaan callback error dan .fail()?

Callback error didefinisikan di dalam objek pengaturan $.ajax, sedangkan .fail() dirangkai pada promise yang dikembalikan. Keduanya menangkap kegagalan request, tetapi .fail() lebih cocok untuk rantai promise dan dapat menangkap error dari callback sukses juga.

Bagaimana cara mengetahui error AJAX terjadi karena timeout?

Periksa argumen textStatus di callback error. Jika nilainya "timeout", berarti request melewati batas waktu yang Anda tetapkan di pengaturan timeout.

Apakah error AJAX perlu ditampilkan ke pengguna?

Hanya jika error memengaruhi tugas pengguna. Error yang tidak berdampak langsung, seperti pembaruan statistik di latar belakang, cukup dicatat di log. Untuk error yang menghalangi pengguna, tampilkan pesan singkat dengan langkah berikutnya.