Cara Mengatasi Express Request Timeout dengan Batas Waktu dan Respons 503

Pasang batas waktu eksplisit lalu kirim respons 503 saat batas terlampaui. Express tidak memutus handler yang menggantung secara otomatis, jadi request macet membuat koneksi menumpuk sampai client timeout. Solusi aman: ukur durasi request, batasi operasi lambat dengan timeout, dan pastikan setiap jalur kode mengirim satu respons.

Penyebab Express Request Timeout Paling Sering

Timeout jarang disebabkan Express sendiri. Penyebabnya hampir selalu handler yang tidak selesai.

  • Handler tidak mengirim respons karena lupa res.send(), lupa next(), atau next(err) tidak ditangani error middleware.
  • Query database lambat, koneksi pool habis, transaksi tidak di-commit, atau index hilang pada tabel besar.
  • Request ke API pihak ketiga menggantung tanpa timeout, lalu menahan event loop Express.
  • await tanpa catch sehingga Promise reject dan fungsi berhenti sebelum respons terkirim.
  • Body JSON besar tanpa limit membuat parsing lama dan memakan memori.

Tambahkan log durasi di awal middleware untuk menemukan titik macet. Periksa stack trace error unhandledRejection, bukan hanya log akses.

Tabel Diagnosis Cepat Request Timeout

Gejala Lokasi Masalah Pemeriksaan awal
Tidak ada respons sama sekali Route atau middleware Cek res.send dan next yang hilang
Hanya route berat yang timeout Database Cek query lambat dan pool
Timeout acak dan jarang API pihak ketiga Cek timeout fetch dan fallback

Jika semua route timeout, curigai middleware global. Jika satu route, periksa query dan request eksternal di route itu. Perbaikan query didahulukan sebelum menaikkan timeout.

Cara Memperbaiki dengan Timeout dan Respons Aman

  1. Reproduksi dengan request yang sama, catat durasi normal dan durasi saat timeout.
  2. Pasang timeout server dan request agar koneksi macet tidak bertahan selamanya.
  3. Tambah middleware timeout yang mengirim 503 konsisten bila handler terlalu lama.
  4. Bungkus operasi lambat dengan Promise.race dan try/catch.
  5. Validasi req.body sebelum query, lalu pastikan respons hanya dikirim sekali.
const express = require('express');
const app = express();

app.use(express.json({ limit: '1mb' }));

function timeout503(ms) {
  return (req, res, next) => {
    const timer = setTimeout(() => {
      if (!res.headersSent) {
        res.status(503).json({ error: 'Service timeout' });
      }
    }, ms);
    res.on('finish', () => clearTimeout(timer));
    next();
  };
}

app.use(timeout503(10000));

app.get('/laporan', async (req, res, next) => {
  try {
    req.setTimeout(10000);
    const data = await Promise.race([
      ambilLaporan(),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('timeout')), 9000)
      )
    ]);
    if (!res.headersSent) res.json({ data });
  } catch (err) {
    next(err);
  }
});

app.use((err, req, res, next) => {
  if (!res.headersSent) res.status(503).json({ error: err.message });
});
  • Jangan retry database atau API tanpa batas, maksimal 2 sampai 3 kali dengan jeda.
  • Selalu cek res.headersSent sebelum kirim respons fallback.

FAQ

Berapa batas timeout ideal untuk Express?

API umum 5 sampai 15 detik, route berat maksimal 30 detik, nilai khas saat penulisan dan sesuaikan dari hasil pengukuran.

Apakah req.setTimeout otomatis menghentikan query database?

Tidak, metode itu hanya menutup koneksi HTTP, query harus dibatalkan terpisah dengan timeout driver database.

Kenapa timeout hanya terjadi di production?

Data lebih besar, pool database lebih padat, dan latensi API eksternal lebih tinggi dibanding environment lokal.