504 Gateway Timeout은 게이트웨이나 프록시가 상위(upstream) 서버로부터 제때 응답을 받지 못해 기다리다 포기했다는 뜻입니다. 백엔드가 완전히 죽은 것은 아니지만, 프록시가 정한 제한 시간 안에 응답을 끝내지 못한 경우입니다.
502가 '백엔드가 깨진 응답을 줬다'라면, 504는 '백엔드가 너무 느려서 응답 자체가 시간 안에 오지 않았다'는 차이가 있습니다. 느린 DB 쿼리, 과부하, 외부 API 지연이 흔한 원인입니다.
GET /api/report/heavy HTTP/1.1
Host: www.example.comHTTP/1.1 504 Gateway Timeout
Content-Type: text/html
Content-Length: 42
<html><body><h1>504 Gateway Timeout</h1></body></html>location /api {
proxy_pass http://backend;
proxy_connect_timeout 5s;
proxy_read_timeout 60s; # raise for legitimately slow endpoints
}# Measure how long the origin actually takes to respond
curl -o /dev/null -s -w 'time_total: %{time_total}s\n' \
http://127.0.0.1:3000/api/report/heavy