# 504 Gateway Timeout

> https://http-status.org/docs/504

**Family:** 5xx Server Error

## Rationale

Server, acting as a gateway or proxy, did not receive a timely response from upstream.

## In Plain Terms

I'm a middleman server, and the server I was trying to talk to took too long to respond, so I gave up waiting.

## Description

The HTTP 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.

## Server Perspective

### Usage
- Return 504 when a backend or origin takes too long and the intermediary times out waiting
- Use it only when this server depends on an upstream response to finish the request
- Upstream server response timeout
- Load balancer timeout waiting for backend
- API gateway timeout
- Proxy timeout to origin server

### Implementation
- Set and monitor realistic upstream deadlines, then log which dependency timed out and after how long
- Return a clear timeout response instead of leaving the client hanging on an open connection

### Common Headers
- No status-specific header is required; include request or trace metadata when it helps operators correlate the upstream timeout

### Body
- A body is optional but helpful; explain that an upstream dependency timed out and include safe retry guidance when appropriate

### Pitfalls
- Do not use 504 for client-to-server request timeouts; that is 408 Request Timeout
- Do not use 504 for malformed upstream responses; that is 502 Bad Gateway
- Client request timeout (use 408 Request Timeout)
- Bad upstream responses (use 502 Bad Gateway)
- Service unavailable (use 503 Service Unavailable)

## Client Perspective

### Pitfalls
- Do not treat 504 as a validation or authentication problem
- Do not assume the upstream timed out before doing the work; unsafe requests may need duplicate protection

## Examples

### Backend API timeout

Backend API took longer than 30 seconds, proxy timed out

**Request:**
```
GET https://api.example.test/api/slow-operation
```

**Response:**
```
504 Gateway Timeout
Content-Type: application/json

{
  "error": "gateway_timeout"
}
```

## Related Codes

- [502 Bad Gateway](/docs/502.md)
- [408 Request Timeout](/docs/408.md)
- [503 Service Unavailable](/docs/503.md)