[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):

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

{
  "type": "/problems/gateway-timeout",
  "title": "Gateway Timeout",
  "status": 504,
  "detail": "The server did not receive a timely response from an upstream service. Please try again.",
  "instance": "/resources/12345"
}

Important

When using 504 Gateway Timeout, you MUST NOT expose the specific upstream service name (e.g., "Firebase", "AWS S3"). Use generic terms like "upstream service" or "backend service" to maintain architectural opacity. See ADP-410 for detailed guidance on abstracting third-party service errors.

Reference

• RFC 9110: 504