Error 504 Gateway Timeout, Penyebab dan Solusinya

Error 504 Gateway Timeout adalah jawaban dari server perantara (proxy) yang sudah menunggu backend terlalu lama lalu berhenti menunggu. Perantara itu bisa Nginx di depan PHP-FPM, load balancer di depan beberapa server aplikasi, atau CDN di depan server asal. Backend-nya sendiri sering kali masih hidup dan masih bekerja, hanya saja jawabannya tidak datang tepat waktu.

Salah membaca 504 bisa mahal. Banyak admin langsung menaikkan semua timeout menjadi beberapa menit. Error-nya memang hilang, tapi proses lambat tetap ada, worker server tertahan lebih lama, dan saat trafik naik, website justru tumbang total. Yang perlu dicari adalah alasan backend lambat, baru kemudian memutuskan apakah timeout memang perlu disesuaikan.

Bagaimana 504 terjadi di rantai server?

Sebuah permintaan biasanya melewati beberapa lapisan: browser, CDN (bila ada), web server atau reverse proxy, lalu aplikasi dan database. Setiap lapisan punya batas waktu sendiri. Error 504 muncul di lapisan yang batasnya habis lebih dulu.

Timeout di setiap lapisan

Tabel berikut merangkum batas waktu yang paling sering terlibat. Nilai bawaan diambil dari dokumentasi resmi masing-masing dan bisa berbeda bila penyedia hosting atau panel mengubahnya.

Perhatikan baris Cloudflare. Kalau kamu memakai Cloudflare dan server asal terlalu lama menjawab, kodenya 524, bukan 504. Menurut dokumentasi Cloudflare, halaman 502 atau 504 bergaya Cloudflare justru berarti error itu dikirim oleh server asalmu, sehingga penyelidikan tetap dimulai di server.

Kenapa nilai timeout perlu selaras

Bayangkan max_execution_time diatur 300 detik, tapi fastcgi_read_timeout di Nginx tetap 60 detik. PHP masih bekerja, tetapi Nginx sudah menyerah di detik ke-60 dan mengirim 504. Pengunjung melihat error, sementara skrip di belakang tetap berjalan sampai selesai dan memakan resource tanpa ada yang menerima hasilnya.

Ada satu detail penting: di Linux, max_execution_time hanya menghitung waktu eksekusi skrip PHP itu sendiri. Waktu menunggu query database, panggilan API luar, atau operasi stream tidak ikut dihitung. Jadi skrip yang lambat karena menunggu database bisa melewati 60 detik tanpa pernah menyentuh batas 30 detik PHP, dan yang menyerah duluan adalah Nginx.

Penyebab paling umum

Query database lambat. Laporan, pencarian, atau halaman arsip dengan query tanpa index bisa memakan puluhan detik. Aktifkan slow query log di MySQL atau MariaDB untuk melihat query mana yang bermasalah.

Panggilan ke layanan luar. Aplikasi yang menunggu API payment gateway, ongkos kirim, atau AI tanpa batas waktu akan ikut lambat saat layanan itu lambat.

Worker PHP-FPM penuh. Kalau semua worker sedang sibuk, permintaan baru mengantre. Antrean yang panjang membuat Nginx menunggu, lalu timeout. Log PHP-FPM biasanya mencatat peringatan bahwa batas pm.max_children sudah tercapai.

Server kehabisan resource. CPU penuh atau RAM habis sampai memakai swap membuat semua proses melambat. Artikel server lambat padahal CPU rendah membahas penyebab yang tidak langsung terlihat, seperti antrean disk.

Pekerjaan berat dijalankan di dalam request. Impor ribuan produk, ekspor laporan besar, atau kirim email massal yang dijalankan langsung saat tombol diklik hampir pasti melewati batas waktu.

Untuk memastikan, buka log error Nginx (tail -n 50 /var/log/nginx/error.log) dan cari pesan upstream timed out (110: Connection timed out) while reading response header from upstream. Pesan itu mencatat URL dan backend yang terlambat, sehingga kamu tahu halaman mana yang perlu diselidiki.

Kapan menaikkan timeout, kapan memperbaiki prosesnya?

Naikkan timeout bila prosesnya memang wajar lama, jarang dipakai, dan hanya diakses orang tertentu. Contohnya halaman admin untuk membuat laporan bulanan yang memakan 90 detik. Di kasus ini, kamu bisa menaikkan fastcgi_read_timeout atau proxy_read_timeout hanya untuk lokasi URL tersebut di konfigurasi Nginx, bukan untuk seluruh website, dan menyelaraskan batas di PHP.

Perbaiki prosesnya bila 504 terjadi di halaman publik, halaman yang sering diakses, atau muncul hanya saat trafik ramai. Halaman publik seharusnya menjawab dalam hitungan detik, bukan menit. Solusinya biasanya menambah index database, memasang cache, memberi batas waktu pada panggilan API luar, atau memindahkan pekerjaan berat ke antrean (queue) yang diproses di latar belakang, lalu memberi tahu pengguna saat hasilnya siap.

Kalau website berada di belakang Cloudflare dan ada proses yang memang butuh lebih dari batas waktunya, dokumentasi Cloudflare menyarankan memindahkan proses itu ke subdomain yang tidak diproksikan (DNS only). Mengubah batasnya hanya bisa dilakukan di paket Enterprise.

Bila semua halaman lambat dan resource server selalu penuh, masalahnya kapasitas. Optimasi tetap perlu, tapi server yang terlalu kecil untuk bebannya akan terus menghasilkan 504 seberapa pun rapi konfigurasinya. Panduan memilih spesifikasi VPS bisa membantu menghitung kebutuhan yang lebih realistis.

Bedanya dengan 502 dan 503

Ketiganya sama-sama error dari sisi server, tapi artinya berbeda. 502 berarti proxy mendapat jawaban tidak sah atau koneksi ke backend ditolak, misalnya PHP-FPM mati. 503 berarti layanan sementara tidak tersedia, misalnya maintenance atau beban berlebih. 504 berarti backend tidak menjawab dalam batas waktu. Penjelasan lengkap tentang 502 ada di artikel error 502 Bad Gateway.