[ADP-201] HTTP Status 504

504 Gateway Timeout Specification

Overview

The 504 Gateway Timeout status code indicates that the server, while 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 status code is defined in RFC 9110, section 15.6.5.

When to Use

The 504 status code SHOULD be used in the following scenarios:

1. Microservices Architecture: When an API gateway or a service aggregator cannot get a response from one or more backend services within a specified timeout period.
2. Proxy Servers: When the server acts as a proxy and cannot get a timely response from an upstream server.
3. Load Balancers: When a load balancer fails to receive a response from a backend server within the timeout period.
4. External Service Dependencies: When an API relies on external services (e.g., third-party APIs) that fail to respond in time.
5. Long-Running Requests: When a request requires significant processing time and exceeds the predefined timeout period.
6. Network Issues: When there are network problems causing delays or packet loss, preventing timely responses.

Example Response (HTTP Problem)

Below is an example of a 504 Gateway Timeout response formatted according to the HTTP Problem Details standard (RFC 9457); let’s say we have a service to integrate with Firebase API but the response from Firebase timeouted:

HTTP/1.1 504 Gateway Timeout
Content-Type: application/problem+json
Retry-After: 120
Content-Length: 350

{
  "type": "https://example.com/problems/gateway-timeout",
  "title": "Gateway Timeout",
  "status": 504,
  "detail": "The server, while acting as a gateway or proxy, did not receive a timely response from Firebase.",
  "instance": "/resources/12345"
}

Reference

• RFC 9110: 504