504 Gateway Timeout

사용법

504 Gateway Timeout 상태 코드는 서버가 업스트림 서버를 위한 프록시나 게이트웨이로 동작하고 있음을 뜻합니다. HTTP 요청을 받은 뒤 서버가 그 요청을 업스트림 서버로 전달하려 했지만, 허용된 시간 안에 아무런 응답도 받지 못한 것입니다.

이는 502 Bad Gateway 상태 코드와 관련이 있습니다. 502는 업스트림 서버가 유효하지 않은 응답을 반환했음을, 504는 응답을 전혀 받지 못했음을 나타냅니다.

플랫폼별 타임아웃은 제각각입니다. Shopify API는 10초의 요청 타임아웃을 적용하며, 그 시간 안에 응답이 준비되지 않으면 504 Gateway Timeout을 반환합니다. Shopify API로 작업하는 개발자는 쿼리를 최적화하고 이 한도를 넘는 작업에는 백그라운드 처리를 사용해야 합니다.

SEO 영향

Googlebot은 5xx 오류를 사이트 전체의 크롤링 속도를 일시적으로 줄이라는 신호로 취급합니다. 이전에 색인된 URL은 처음에는 유지되지만, 장애가 길어지면 Google이 색인에서 제거합니다. 504 응답과 함께 반환된 콘텐츠는 무시됩니다. Google은 문서에서 500, 502, 503을 서버 오류로 명시적으로 묶어 다룹니다. 504도 같은 범주의 일반적인 5xx 오류에 속합니다. robots.txt 파일의 5xx 오류는 사이트의 다른 모든 페이지가 200을 반환하더라도 훨씬 심각합니다. Google은 최대 12시간 동안 크롤링을 중단한 뒤, 최대 30일까지 캐시된 사본으로 대체합니다. 오류가 계속되면 Google은 해당 사이트를 완전히 색인에서 제외합니다. Bingbot 역시 5xx 응답을 크롤링 실패로 취급합니다. 5xx 오류가 지속되면 Bing에서 색인이 이루어지지 않습니다.

예시

클라이언트가 리소스를 요청하고, 업스트림 서버가 HTTP 응답을 반환하지 않았으므로 서버는 504 Gateway Timeout 상태 코드로 응답합니다.

요청

GET /news HTTP/1.1
Host: example.com

응답

HTTP/1.1 504 Gateway Timeout
Content-Type: text/html; charset=UTF-8
Content-Length: 128

<html>
  <head>
    <title>Gateway Timeout</title>
  </head>
  <body>
    <p>The server is not responding.</p>
  </body>
</html>

해결 방법

프록시가 백엔드의 응답을 기다리다 타임아웃되었습니다. 해결책은 타임아웃을 늘리거나 백엔드를 더 빠르게 만드는 것 둘 중 하나입니다.

프록시 타임아웃을 늘리세요.

nginx의 기본 타임아웃은 60초입니다. server나 location 블록에서 해당 지시문들의 값을 올리세요.

Apache에서는 가상 호스트나 전역 설정에 ProxyTimeout 300을 설정하세요. mod_proxy_fcgi를 사용할 때는 ProxyPassMatch 지시문의 timeout 매개변수가 대기 시간을 제어합니다.

백엔드 타임아웃을 맞추세요. 백엔드 프로세스에는 그와 같거나 더 긴 타임아웃이 필요합니다. PHP에서는 php.ini의 max_execution_time과 PHP-FPM 풀 설정의 request_terminate_timeout을 올리세요. Node.js에서는 server.timeout을 설정하세요. Gunicorn에서는 —timeout을 사용하세요.

느린 백엔드 작업을 최적화하세요. 타임아웃은 느린 작업의 증상입니다. 요청을 프로파일링해 병목을 찾아내세요.

플랫폼이 강제하는 타임아웃을 지키세요. 호스팅 플랫폼은 일반적인 프록시 기본값보다 짧은 엄격한 한도를 적용합니다. Shopify는 10초 상한을 둡니다. 플랫폼 한도를 넘는 작업은 백그라운드 작업으로 넘기고, HTTP 요청을 붙잡아 두는 대신 결과를 폴링하세요.

네트워크 경로를 점검하세요. curl이나 telnet으로 프록시와 백엔드 사이의 연결성을 확인하세요. 패킷 손실, DNS 지연, 중간 홉의 방화벽 규칙이 모두 타임아웃에 기여합니다. traceroute를 실행해 느린 네트워크 구간을 찾아내세요.

캐싱을 추가하세요. 멱등한 요청이라면 프록시 계층에서 응답을 캐시하여 느린 백엔드 호출의 반복을 피할 수 있습니다. nginx의 proxy_cache_path와 Apache의 mod_cache 모두 업스트림 부하를 줄여 줍니다.

코드 참고

.NET

HttpStatusCode.GatewayTimeout

Rust

http::StatusCode::GATEWAY_TIMEOUT

Rails

:gateway_timeout

http.StatusGatewayTimeout

Symfony

Response::HTTP_GATEWAY_TIMEOUT

Python3.5+

http.HTTPStatus.GATEWAY_TIMEOUT

Java

java.net.HttpURLConnection.HTTP_GATEWAY_TIMEOUT

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_GATEWAY_TIMEOUT

Angular

@angular/common/http/HttpStatusCode.GatewayTimeout