HTTP 504 Gateway Timeout — nginx, Proxy Timeouts & Fix Guide

When to Return 504

Typically generated by nginx, load balancers, or CDNs when your application server takes too long. Return 504 from application code when calling an upstream service and it exceeds your timeout.

Common Causes

• nginx proxy_read_timeout exceeded
• Upstream database query taking too long
• Third-party API call timing out
• Slow downstream service in a microservice chain
• Large file processing exceeding timeout

HTTP Response Example

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json

{"error": "Gateway Timeout", "message": "Upstream did not respond in time"}

Code Examples

// Call upstream with timeout
app.get('/data', async (req, res) => {
  const controller = new AbortController()
  const timeout = setTimeout(() => controller.abort(), 5_000)

  try {
    const response = await fetch('https://slow-upstream/data', {
      signal: controller.signal,
    })
    clearTimeout(timeout)
    res.json(await response.json())
  } catch (err) {
    clearTimeout(timeout)
    if (err.name === 'AbortError') {
      return res.status(504).json({ error: 'Gateway Timeout', message: 'Upstream timed out after 5s' })
    }
    res.status(502).json({ error: 'Bad Gateway' })
  }
})

export async function GET() {
  try {
    const response = await fetch('https://slow-api/data', {
      signal: AbortSignal.timeout(5_000), // 5s timeout
    })
    return Response.json(await response.json())
  } catch (err) {
    if (err instanceof DOMException && err.name === 'TimeoutError') {
      return Response.json({ error: 'Gateway Timeout' }, { status: 504 })
    }
    return Response.json({ error: 'Bad Gateway' }, { status: 502 })
  }
}

Related Status Codes