What it means
A proxy timing out on the origin. The important operational detail: the upstream request may well have succeeded after the proxy gave up, so a 504 on a non-idempotent call cannot be safely retried without an idempotency key.
- Class
- 5xx Server error
- Defined in
- RFC 9110 §15.6.5
- Cached by default
- No
When you receive a 504
- A proxy waited for the origin and gave up. The request may still have completed behind it.
- Before retrying a
POST, check whether it went through - or send an idempotency key so a retry is safe. - Work that takes minutes belongs in a background job:
202 Acceptedand a URL to poll, not one long request.
When you send a 504
- Your proxy sends it when the upstream exceeds its read timeout -
proxy_read_timeoutin nginx, 60 seconds by default. - Raise the timeout only if the work really is that slow; otherwise fix the slow query or move the work to a job.
- Keep the proxy's timeout longer than the app's own, so the app can return a meaningful error first.
On the wire
HTTP/1.1 504 Gateway Timeout Server: nginx Content-Type: text/html <html><body><h1>504 Gateway Time-out</h1></body></html>