HTTPTools

HTTP 504 Gateway Timeout

중간자가 기다리다 포기함: 업스트림 서버가 프록시의 제한 시간 내에 응답하지 않았습니다.

HTTP 504의 의미

HTTP 504 Gateway Timeout은 업스트림 서버로 보낸 요청이 타임아웃 내에 아무런 응답도 받지 못했을 때 프록시, 로드 밸런서 또는 CDN이 발생시킵니다. 업스트림이 잘못된 응답을 보낸 502와 달리, 504는 제시간에 아예 응답하지 않은 경우입니다.

근본 원인은 거의 항상 배후에서 벌어지는 느린 작업입니다: 비용이 큰 데이터베이스 쿼리, 응답이 없는 외부 API, 또는 부하로 고갈된 애플리케이션 스레드 풀 등입니다.

504 오류의 일반적인 원인

  • 느린 데이터베이스 쿼리나 인덱스 누락으로 인해 특정 엔드포인트가 프록시 허용 시간보다 오래 걸리는 경우.
  • 애플리케이션이 그 자체로 느리거나 다운된 외부 API를 기다리고 있는 경우.
  • 백엔드가 포화 상태: 모든 워커가 사용 중이고, 요청이 타임아웃을 넘겨 대기열에 쌓이는 경우.
  • 프록시와 업스트림 사이의 네트워크 문제(라우팅, 패킷 손실, DNS).
  • 타임아웃 불일치: 애플리케이션은 정당하게 60초가 필요한데 프록시가 30초에서 끊어버리는 경우.

방문자 입장에서 해결하는 방법

  • 잠시 후 다시 시도하세요 — 단발성 504는 대개 장애가 아니라 하나의 느린 요청일 뿐입니다.
  • 제출한 작업(결제, 주문)이 있다면 재시도하기 전에 실제로 처리되었는지 확인하세요.

개발자로서 해결하는 방법

  • 액세스 로그/APM에서 느린 엔드포인트를 찾으세요: 쿼리를 개선하고, 인덱스를 추가하고, 결과를 캐시하세요.
  • 느린 작업은 백그라운드 작업으로 옮기고, 클라이언트가 폴링할 수 있는 상태 값과 함께 빠르게 응답을 반환하세요.
  • 가장 느린 구간이 어디인지 알고 의도적으로 설계할 수 있도록 타임아웃 예산을 전체 경로(app < proxy < CDN)에 맞춰 정렬하세요.
  • 불안정한 외부 API로 인해 워커가 멈추지 않도록 서킷 브레이커를 도입하세요.

응답 예시

HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

<html><body><h1>504 Gateway Timeout</h1></body></html>

자주 묻는 질문

504와 502의 차이는 무엇인가요?

504는 업스트림이 타임아웃 내에 전혀 응답하지 않았다는 의미이고, 502는 유효하지 않은 응답을 보냈다는 의미입니다.

504는 사용자의 연결 문제인가요?

아니요 — 이는 사이트의 프록시와 백엔드 사이의 문제입니다. 사용자의 네트워크는 정상입니다.

504를 받았다면 제출한 요청이 처리된 건가요?

그럴 수도 있습니다 — 타임아웃은 응답에 걸린 것이지, 반드시 처리 자체에 걸린 것은 아닙니다. 멱등이 아닌 작업을 무작정 재시도하기 전에 상태를 확인하세요.