504 Gateway Timeout

Description

The 504 Gateway Timeout status code indicates that a server acting as a gateway or proxy did not receive a timely response from an upstream server it needed to access in order to complete the request. This timeout occurs when the gateway server has waited too long for a response from the upstream server.

Common scenarios where a 504 Gateway Timeout might occur include:

An API gateway waits too long for a response from a backend service
A proxy server cannot get a timely response from the origin server
A load balancer's connection to a backend server times out
A CDN (Content Delivery Network) times out while waiting for content from the origin server
Long-running database queries or operations that exceed timeout thresholds

Unlike a 502 Bad Gateway which indicates an invalid response was received, a 504 Gateway Timeout specifically indicates that no response was received within the allotted time.

Syntax

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

{
  "error": {
    "code": 504,
    "message": "Gateway Timeout",
    "details": "The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server."
  }
}

Examples

Example 1: API Gateway to Microservice Timeout

An API gateway forwards a request to a microservice, but the microservice takes too long to respond.

Request:

GET /api/analytics/report HTTP/1.1
Host: example.com
Accept: application/json

Response:

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

{
  "error": {
    "code": 504,
    "message": "Gateway Timeout",
    "details": "The analytics service took too long to respond. The report generation may be too complex or the service is overloaded."
  }
}

Example 2: Proxy Server to Database Timeout

A web server acting as a proxy times out while waiting for a database query to complete.

Request:

GET /api/search?q=complex+query&filters=many,complex,filters HTTP/1.1
Host: example.com
Accept: application/json

Response:

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

{
  "error": {
    "code": 504,
    "message": "Gateway Timeout",
    "details": "The search operation timed out. Please try simplifying your search query or reducing the number of filters applied."
  }
}

Example 3: CDN to Origin Server Timeout

A CDN attempts to fetch content from the origin server, but the origin server takes too long to respond.

Request:

GET /large-video-file.mp4 HTTP/1.1
Host: cdn.example.com
Range: bytes=0-1048576

Response:

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

{
  "error": {
    "code": 504,
    "message": "Gateway Timeout",
    "details": "Our CDN could not retrieve the requested content from the origin server within the time limit."
  }
}

Summary

The 504 Gateway Timeout status code indicates that a server acting as a gateway or proxy did not receive a timely response from an upstream server. It signals to the client that the request failed not because of an error in the client's request or the gateway server itself, but because of a timeout while waiting for another server in the chain.

Key points about 504 Gateway Timeout:

It specifically indicates a timeout issue, not other types of communication problems
It's common in multi-tier architectures involving proxies, gateways, or microservices
The timeout is often configurable on the gateway or proxy server
It may indicate that the upstream server is overloaded, experiencing high latency, or processing a complex operation
Unlike 503 Service Unavailable, which indicates the server itself is unavailable, 504 indicates a timeout in server-to-server communication
Clients may retry the request, potentially with simplified parameters if applicable
For operations that inherently take a long time, servers should consider using asynchronous processing patterns instead of synchronous request-response