# 504 Gateway Timeout: upstream response timeout

- **ID:** `api/http-504-gateway-timeout-upstream`
- **Domain:** api
- **Category:** network_error
- **Error Code:** `504`
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

An API gateway or reverse proxy (e.g., Nginx, AWS API Gateway) timed out while waiting for the upstream service to respond, typically due to slow processing or network issues.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Nginx 1.25.0 | active | — | — |
| AWS API Gateway (2024) | active | — | — |
| Kong 3.6.0 | active | — | — |
| HAProxy 2.9.0 | active | — | — |

## Workarounds

1. **Increase the upstream timeout in the gateway configuration. For Nginx, add to the location block: `proxy_read_timeout 60s; proxy_connect_timeout 30s;`. Then reload: `nginx -s reload`.** (85% success)
   ```
   Increase the upstream timeout in the gateway configuration. For Nginx, add to the location block: `proxy_read_timeout 60s; proxy_connect_timeout 30s;`. Then reload: `nginx -s reload`.
   ```
2. **Optimize the upstream service's response time by adding caching, database query optimization, or asynchronous processing. For example, use Redis caching for frequent queries.** (80% success)
   ```
   Optimize the upstream service's response time by adding caching, database query optimization, or asynchronous processing. For example, use Redis caching for frequent queries.
   ```
3. **Implement a retry mechanism with exponential backoff in the client, but ensure idempotency. Example in Python: `requests.get(url, timeout=10); time.sleep(2**attempt)`.** (75% success)
   ```
   Implement a retry mechanism with exponential backoff in the client, but ensure idempotency. Example in Python: `requests.get(url, timeout=10); time.sleep(2**attempt)`.
   ```

## Dead Ends

- **** — The timeout occurs at the gateway, not the client; client-side changes are irrelevant. (90% fail)
- **** — Restarting resets the service but does not address underlying performance bottlenecks like slow queries or resource leaks. (70% fail)
- **** — Removing timeouts allows slow requests to accumulate, potentially crashing the service. (80% fail)