Error 502 dan 504 di Website: Cara Mencari Sumber Masalah tanpa Menebak

Halaman website yang tiba-tiba menampilkan 502 Bad Gateway atau 504 Gateway Timeout sering membuat orang langsung menyalahkan server utama. Padahal, di antara browser dan aplikasi biasanya ada beberapa lapisan: CDN, reverse proxy, web server, PHP-FPM, API, hingga database.

Karena itu, langkah pertama bukan langsung me-restart semua layanan atau menaikkan spesifikasi VPS. Pahami dulu jenis errornya, lalu telusuri jalur request dari depan ke belakang.

Perbedaan 502 dan 504

502 Bad Gateway berarti server yang bertindak sebagai gateway atau proxy menerima respons yang tidak valid dari server di belakangnya. Misalnya, Nginx meneruskan request ke PHP-FPM, tetapi koneksi ditutup secara tidak normal atau respons yang diterima tidak sesuai harapan. Definisi ini sejalan dengan RFC 9110 dan dokumentasi MDN. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status?utm_source=openai))

504 Gateway Timeout berarti gateway atau proxy tidak menerima jawaban tepat waktu dari server upstream. Upstream adalah layanan di belakang proxy, seperti aplikasi PHP, API internal, atau database yang dipanggil aplikasi. Jadi, 504 lebih mengarah pada masalah waktu tunggu, meskipun penyebab akhirnya bisa beragam. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/504?utm_source=openai))

Analogi sederhananya: 502 seperti menerima jawaban yang rusak atau tidak masuk akal dari dapur. 504 seperti menunggu terlalu lama sampai pelayan memutuskan bahwa pesanan tidak kunjung selesai.

Jangan langsung mengubah timeout

Menaikkan timeout memang kadang membantu request yang secara alami membutuhkan waktu lama. Namun, itu bukan solusi untuk query yang macet, proses PHP yang kehabisan worker, atau koneksi ke database yang gagal.

Jika timeout dinaikkan tanpa mencari akar masalah, request yang bermasalah justru akan bertahan lebih lama. Pada trafik tinggi, banyak request seperti ini dapat memenuhi worker dan membuat halaman lain ikut lambat.

Di Nginx, misalnya, proxy_read_timeout mengatur berapa lama proxy menunggu respons dari server yang dituju. Pengaturan ini hanya mengubah batas tunggu, bukan memperbaiki layanan upstream yang lambat atau tidak sehat. ([nginx.org](https://nginx.org/en/docs/http/ngx_http_proxy_module.html?utm_source=openai))

Langkah diagnosis yang bisa dicoba

1. Pastikan error terjadi pada semua halaman

Coba buka halaman utama, halaman login, halaman admin, dan endpoint API jika tersedia. Catat polanya:

• Jika semua URL gagal, kemungkinan masalah ada pada koneksi proxy ke origin, web server, atau server sedang tidak aktif.
• Jika hanya satu halaman gagal, curigai kode aplikasi, query database, integrasi API, atau data tertentu.
• Jika hanya pengguna tertentu yang mengalami masalah, periksa jaringan, VPN, DNS, atau konfigurasi proxy di sisi pengguna.

Pengujian dari jaringan berbeda juga berguna. Coba koneksi seluler, perangkat lain, atau layanan pemantau eksternal. Tujuannya bukan sekadar memastikan website bisa dibuka, tetapi mencari apakah kegagalan bersifat umum atau lokal.

2. Periksa status layanan dari lapisan paling belakang

Jika Anda memiliki akses server, cek apakah layanan penting masih berjalan. Contoh pada sistem Linux dengan systemd:

sudo systemctl status nginx
sudo systemctl status php-fpm
sudo systemctl status mysql

Nama layanan PHP-FPM dapat berbeda, misalnya php8.2-fpm. Jangan menyalin nama layanan secara mentah; sesuaikan dengan versi yang terpasang.

Periksa juga penggunaan CPU, RAM, dan disk. RAM yang habis dapat memicu proses dihentikan oleh sistem. Disk yang penuh dapat membuat aplikasi gagal menulis session, log, cache, atau file sementara.

3. Baca log pada waktu yang sama

Jangan hanya melihat log terbaru secara umum. Cocokkan waktu ketika error muncul dengan catatan pada beberapa lapisan:

• Log Nginx atau Apache untuk melihat kegagalan koneksi ke upstream.
• Log PHP-FPM untuk melihat worker yang berhenti, penuh, atau mencapai batas proses.
• Log aplikasi untuk menemukan exception, request yang terlalu lama, atau kegagalan API.
• Log database untuk melihat koneksi putus, lock, atau query yang berjalan terlalu lama.

Pesan seperti connection refused biasanya berbeda maknanya dari upstream timed out. Yang pertama mengarah pada layanan yang tidak menerima koneksi. Yang kedua menunjukkan koneksi mungkin berhasil dibuat, tetapi respons tidak selesai dalam batas waktu.

4. Pisahkan masalah aplikasi dari masalah infrastruktur

Jika endpoint sederhana seperti /health berhasil, tetapi halaman laporan gagal, kemungkinan infrastruktur dasar masih hidup dan masalah berada pada proses aplikasi atau dependensinya.

Endpoint pemeriksaan kesehatan sebaiknya ringan. Jangan membuatnya menjalankan laporan besar atau memanggil semua layanan eksternal. Pemeriksaan seperti ini cukup memastikan aplikasi dapat menerima request dan, bila perlu, terhubung ke dependency penting.

5. Uji dependency satu per satu

Aplikasi modern jarang bekerja sendirian. Satu halaman dapat memanggil database, API pembayaran, layanan email, object storage, dan sistem autentikasi. Jika salah satu layanan lambat, request utama bisa ikut menunggu.

Gunakan waktu respons dan log untuk melihat dependency mana yang paling lama. Bila memungkinkan, pasang timeout terpisah untuk setiap panggilan keluar. Timeout API pembayaran tidak harus sama dengan timeout query database.

Apa artinya bagi pemilik website?

Error 502 atau 504 bukan selalu tanda bahwa server harus diganti. Sering kali masalahnya lebih spesifik: satu proses macet, worker terlalu sedikit, query tidak efisien, koneksi database habis, atau layanan eksternal tidak merespons.

Yang penting adalah memiliki observabilitas dasar: log yang mudah dicari, waktu respons, status layanan, penggunaan resource, dan informasi request yang aman untuk ditelusuri. Tanpa data tersebut, proses perbaikan berubah menjadi tebak-tebakan.

Yang bisa dilakukan sekarang

1. Buat daftar komponen yang dilewati request: CDN, proxy, web server, runtime, aplikasi, database, dan API eksternal.
2. Sediakan halaman atau endpoint health check yang ringan.
3. Pastikan log menyimpan waktu, endpoint, dan durasi request tanpa membocorkan password atau token.
4. Tetapkan timeout untuk koneksi keluar dan gunakan retry secara hati-hati.
5. Uji halaman penting setelah setiap perubahan konfigurasi.
6. Jangan memperbesar timeout sebelum mengetahui apakah sumbernya benar-benar proses yang lambat.

Jika website dikelola oleh penyedia hosting, kirimkan waktu kejadian, URL yang gagal, kode error, dan hasil pengujian dari jaringan berbeda. Informasi tersebut jauh lebih berguna daripada sekadar mengatakan, “Website sedang error.”

Intinya, 502 dan 504 adalah petunjuk tentang hubungan antar-layanan, bukan diagnosis final. Dengan membedakan respons yang tidak valid dari respons yang terlambat, Anda dapat mempersempit masalah dan memilih perbaikan yang lebih masuk akal.

Sumber & bacaan lebih lanjut

• HTTP response status codes - MDN Web Docs
• 504 Gateway Timeout - MDN Web Docs
• RFC 9110: HTTP Semantics
• NGINX ngx_http_proxy_module Documentation

– Rio Yotto @rioyotto