504 Gateway Timeout: 웹 개발자를 위한 원인 분석 및 복구 절차

최종 업데이트: 2026년 6월. 서버리스/플랫폼의 하드 타임아웃, LLM 스트리밍 백엔드, 비동기 처리 패턴 등 최신 환경을 반영해 보강했습니다. 원문의 원인 분석과 복구 절차는 그대로 유효합니다.

30초 요약 (TL;DR)

• 504 Gateway Timeout은 게이트웨이/프록시가 업스트림의 응답을 제한 시간 내에 받지 못했다는 신호입니다. 핵심은 “지연”이며, 502(잘못된 응답)·503(수용 불가)과 다릅니다.
• 5대 원인: ① 느린 애플리케이션 처리(N+1·무거운 연산), ② 느린 의존성(DB·외부 API), ③ 프록시/게이트웨이 타임아웃 미정렬, ④ 리소스 고갈(스레드·커넥션 풀), ⑤ 스트리밍/프로토콜 미스매치.
• 1차 진단: 어느 홉의 타임아웃인지(LB ↔ 프록시 ↔ 앱) 식별 → 느린 엔드포인트/쿼리 특정 → 타임아웃 매트릭스 점검.
• 즉시 실행: Nginx 로그에 $upstream_response_time 추가, DB slow query log 활성화, 분산 트레이싱으로 지연 스팬 확인.
• 함정: 타임아웃을 무작정 늘리는 것은 해결이 아니라 연기입니다. 근본은 지연 원인 제거 또는 비동기화입니다.

웹 서비스를 운영하다 보면 가장 당혹스러운 순간 중 하나가 바로 504 Gateway Timeout 오류입니다. 특히 트래픽이 몰리는 피크 타임이나 배포 직후에 발생하면 사용자는 빈 화면과 함께 떠난 뒤 돌아오지 않습니다. 이 글은 웹 개발자가 504 오류를 빠르게 진단하고 복구하며, 재발을 방지하는 데 필요한 실전 전략을 담은 종합 가이드입니다.

504 Gateway Timeout이란?

504 Gateway Timeout은 게이트웨이 또는 프록시 서버가 업스트림(백엔드) 서버로부터 응답을 제때 받지 못했을 때 반환하는 HTTP 상태 코드입니다. 즉, 클라이언트의 요청은 게이트웨이까지 도착했지만, 그 뒤에 있는 애플리케이션 서버나 외부 API, 또는 다른 서비스가 정해진 시간 내에 응답하지 않아 타임아웃이 발생한 상황입니다.

502, 503과의 차이

• 502 Bad Gateway: 업스트림 서버가 잘못된 응답을 반환하거나 연결 자체가 비정상일 때.
• 503 Service Unavailable: 서버가 과부하이거나 유지보수로 일시적으로 서비스를 제공할 수 없을 때.
• 504 Gateway Timeout: 업스트림 서버의 응답이 시간 내에 오지 않았을 때.

핵심은 504는 “지연” 문제라는 점입니다. 네트워크 지연, DB 지연, 외부 API 지연, 또는 게이트웨이/프록시의 타임아웃 설정이 너무 짧은 경우 등 다양한 원인이 숨어 있습니다.

요청 경로와 타임아웃이 발생하는 지점

일반적인 요청 경로를 텍스트로 그려보면 다음과 같습니다:

사용자 → CDN/역방향 프록시(예: Cloudflare, Nginx, HAProxy) → L7 로드밸런서(ALB/Ingress) → 애플리케이션 서버(Express, Spring, Django 등) → 데이터베이스/캐시/외부 API

타임아웃은 각 구간에서 독립적으로 발생할 수 있습니다.

• L4/L7 로드밸런서의 idle timeout
• 프록시의 읽기/쓰기 타임아웃
• 애플리케이션 런타임/프레임워크의 요청 처리 타임아웃
• DB 쿼리 타임아웃 또는 커넥션 풀 대기 시간
• 외부 API 호출 타임아웃

따라서 504를 해결하려면 어느 구간에서 응답이 지연되었는지를 좁혀가는 것이 첫걸음입니다.

흔한 원인 Top 카테고리

1) 애플리케이션 처리 지연

• CPU 바운드 작업, GC Stop-the-world, 동기 I/O 블로킹
• 스레드 풀/워커 풀 고갈, 이벤트 루프 블로킹(Node.js)
• 비효율적 알고리즘, 대용량 직렬화/압축

2) 데이터베이스/캐시/외부 API 지연

• 인덱스 부재로 인한 테이블 스캔, 락 경합, 커넥션 풀 부족
• 외부 API 장애/지연, 잘못된 재시도 전략으로 폭풍 재시도 발생
• 캐시 미스 폭증, 쿼리 캐시 설계 미비

3) 프록시/게이트웨이 타임아웃 설정

• Nginx proxy_read_timeout, Apache ProxyTimeout, HAProxy timeout 설정이 실제 p95/p99 지연보다 짧음
• CDN/로드밸런서 idle_timeout 미스매치

4) 네트워크/보안 이슈

• 방화벽/보안그룹 규칙, NAT 게이트웨이 이슈
• MTU/PMTU 블랙홀, 라우팅 지연, DNS 지연

5) 리소스 고갈

• 파일 디스크립터(FD) 한도 초과
• 커넥션 수 과다, 큐 대기 증가
• 디스크 I/O 병목

6) 프로토콜/패턴 미스매치

• Long polling/SSE/WebSocket에 맞지 않는 프록시/로드밸런서 타임아웃
• 업스트림 Keep-Alive 미활성화로 불필요한 핸드셰이크 증가

10분 복구 플레이북(First Response)

장애가 터졌을 때 즉시 실행할 수 있는 절차입니다.

1. 영향 범위 파악

• 특정 경로나 메서드만 문제인지, 전체 트래픽인지.
• p50/p95 지연과 에러율 그래프 확인(APM/모니터링).

2. 빠른 재현 및 경계 축소

• 외부에서:
  • curl -v https://example.com/endpoint --max-time 10
• 게이트웨이 서버에서 업스트림으로:
  • curl -v http://app:8080/endpoint --connect-timeout 2 --max-time 5
• 애플리케이션 서버에서 DB로:
  • 데이터베이스 클라이언트로 단순 쿼리 실행

3. 로그 확인

• Nginx error.log에서 upstream timed out 메시지 확인.
• 애플리케이션 로그에서 특정 요청의 처리 시간, 예외 스택 추적 확인.
• DB 슬로우 쿼리 로그/락 대기 확인.

4. 최근 변경사항 되돌리기

• 직전 배포 롤백.
• 설정 변경/피처 플래그 되돌리기.
• 문제가 특정 AZ/리전/릴리즈에 국한되면 트래픽 우회/축소.

5. 임시 완화(Mitigation)

• 임계 경로 캐시 강화, 비필수 기능(외부 API 호출 등) 셧다운.
• 오토스케일 수동 상향/병렬 워커 증설.
• Queue로 우회(동기 처리 → 비동기 처리).

6. 증상 완화 후 근본 원인 분석(RCA) 착수.

로그/지표/트레이싱으로 정확히 집게 찌르기

Nginx 로그에 타이밍 값 추가

upstream 응답 시간과 요청 전체 시간을 로그에 포함하면 병목을 구분하기 쉽습니다.

log_format timed '$remote_addr - $request '
                 'status=$status rt=$request_time urt=$upstream_response_time '
                 'ust=$upstream_status';
access_log /var/log/nginx/access.log timed;

• rt: 전체 요청 시간
• urt: 업스트림 응답 시간
• ust: 업스트림 상태 코드(게이트웨이 관점)

HAProxy 타이밍 필드

HAProxy는 Tq/Tw/Tc/Tr/Tt 등 세부 타이밍을 제공합니다. Tw(대기 시간), Tr(서버 응답 시간)으로 어디서 지연되는지 파악합니다.

분산 트레이싱

• 요청에 trace-id를 심고, 게이트웨이→애플리케이션→DB/외부 API 전 구간을 상관관계로 묶습니다.
• p95/p99에 집중해 병목 서비스/쿼리를 확인합니다.

원인별 복구 절차와 설정 예시

Nginx(역방향 프록시) 타임아웃/커넥션

proxy_connect_timeout 5s;      # 업스트림 연결 시도 제한
proxy_send_timeout 60s;        # 업스트림으로 보낼 때
proxy_read_timeout 60s;        # 업스트림 응답 대기
send_timeout 60s;              # 클라이언트에게 보낼 때
keepalive_timeout 65s;         # 클라이언트 Keep-Alive
upstream backend {
  server app1:8080 max_fails=3 fail_timeout=10s;
  server app2:8080 max_fails=3 fail_timeout=10s;
  keepalive 64;                # 업스트림 Keep-Alive로 커넥션 재사용
}

주의: 단순히 timeout 값을 키우면 사용자 체감은 나아질 수 있지만, 리소스 점유가 증가해 더 큰 장애로 번질 수 있습니다. 타임아웃 상향은 증상 완화용이며, 근본 원인(느린 쿼리, 블로킹 코드) 해결이 우선입니다.

PHP-FPM/fastcgi의 경우:

fastcgi_read_timeout 60s;

Apache/HAProxy

• Apache:

  TimeOut 60
  ProxyTimeout 60
  KeepAlive On
  

• HAProxy:

  defaults
    timeout connect 5s
    timeout client  60s
    timeout server  60s
    timeout http-keep-alive  10s
    maxconn 5000
  

애플리케이션 런타임

• Node.js/Express

  // 서버 타임아웃 방어
  const server = app.listen(3000);
  server.headersTimeout = 65_000; // 헤더 교환 시간
  server.requestTimeout = 60_000; // 요청 처리 제한
  
  // 외부 API 호출 시 타임아웃/재시도/서킷브레이커
  const axiosInstance = axios.create({ timeout: 3000 });
  

  • CPU 바운드 작업을 워커 스레드/큐로 분리.
  • 이벤트 루프 블로킹 점검(클로저/대용량 JSON 처리 최적화).

• Python/Gunicorn/Uvicorn

  # Gunicorn
  workers = 4
  worker_class = "uvicorn.workers.UvicornWorker"
  timeout = 60           # 워커 응답 대기
  keepalive = 5
  

  • requests 사용 시:

    requests.get(url, timeout=(2, 3))  # (connect, read)
    

• Go

  srv := &http.Server{
    Addr:              ":8080",
    ReadTimeout:       10 * time.Second,
    ReadHeaderTimeout: 10 * time.Second,
    WriteTimeout:      60 * time.Second,
    IdleTimeout:       60 * time.Second,
  }
  
  client := &http.Client{
    Timeout: 3 * time.Second, // 전체 요청 타임아웃
  }
  

  • context.WithTimeout으로 다운스트림 호출에 데드라인 전파.

• Java/Spring

  • Tomcat/Undertow 커넥터 타임아웃 설정.
  • RestTemplate/WebClient에 커넥션/소켓 타임아웃, 재시도 정책 명시.

클라우드/플랫폼 설정

• AWS ALB: idle_timeout 기본 60s. SSE/롱폴링이면 증가 필요. 단, 백엔드보다 길면 안 됨.
• Cloudflare: 524(업스트림 타임아웃)과 522(연결 실패) 구분. 장시간 처리에는 “Bypass cache” 경로/워커 활용.
• GCP Cloud Run/App Engine: 요청 타임아웃 상한 확인(예: 60분/10분 등 서비스별 상이).
• Kubernetes Ingress-NGINX:

  metadata:
    annotations:
      nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "60"
      nginx.ingress.kubernetes.io/proxy-next-upstream: "error timeout http_502 http_503"
  

• Istio/Envoy: VirtualService에서 timeout 명시 및 재시도 정책 설정.

데이터베이스 튜닝과 타임아웃

• 인덱스: EXPLAIN으로 풀스캔 제거.
• 락/경합: 트랜잭션 범위 축소, 격리수준 점검, 배치 분할.
• 커넥션 풀: 과도한 커넥션 수는 오히려 문맥전환 비용을 높임. 적정 수 산정.
• 타임아웃:
  • PostgreSQL: statement_timeout, lock_timeout
  • MySQL: max_execution_time, innodb_lock_wait_timeout
• 캐시: Redis로 Hot Key 분산, 캐시 만료 스톰 방지(랜덤ized TTL, stale-if-error).
• 읽기 부하: 리드 레플리카, CQRS, 사전 집계.

외부 API 안정화

• 짧은 클라이언트 타임아웃과 지수 백오프 재시도.
• 서킷 브레이커로 장애 전파 차단.
• 타임아웃 전파: 클라이언트 전체 데드라인보다 다운스트림 타임아웃을 짧게.
• 폴백/축소: 필수 기능만 유지, 비필수 호출은 스킵/대체 데이터 사용.
• 요청 중복 허용을 위한 idempotency 키 도입.

네트워크/시스템

• 보안 그룹/NACL/방화벽 규칙 재확인(특히 이스트-웨스트 트래픽).
• DNS: 느린 리졸브 또는 잘못된 레코드. /etc/resolv.conf 및 캐시 점검.
• MTU 문제(특히 VPN/터널): TCP MSS 클램핑 또는 PMTU 디버깅.
• FD/커넥션: ulimit -n 상향, 시스템 커널 파라미터(net.core.somaxconn) 조정.

방지 전략: 설계로 타임아웃을 이겨내기

타임아웃과 재시도 “예산화”

• 전체 요청 데드라인을 먼저 정하고, 다운스트림별 타임아웃을 그보다 짧게 배분.
• 재시도는 빠르고 제한적으로(짧은 타임아웃 + 1~2회 + 지수 백오프).
• 장기 지연을 유발하는 재시도 폭풍을 피하기 위해 서킷 브레이커와 버짓 기반 재시도 적용.

비동기화와 오프로드

• 1초 이상 걸리는 작업은 큐(예: SQS, Kafka, Sidekiq)로 넘기고, 요청은 작업 ID만 반환.
• 클라이언트는 폴링/웹훅으로 결과 수신.

캐싱/프리컴퓨팅

• 읽기 많은 엔드포인트는 CDN 캐시, Edge 컴퓨팅, 사전 렌더링.
• 캐시 무효화 전략과 TTL 설계.

백프레셔와 레이트 리미팅

• 큐가 차면 429/503으로 조기 거절, 시스템을 보호.
• 우선순위 큐로 핵심 트래픽 보호.

헬스체크/오토스케일

• 지연 증가 시 워크로드 확장.
• 슬로우 스타트/워밍업으로 콜드스타트 지연 완화.

실전 커맨드/툴킷 모음

• 연결/응답 진단:
  • curl -v https://example.com --max-time 10 --connect-timeout 2
  • curl -v http://app:8080/health
• DNS:
  • dig +trace api.partner.com
  • nslookup api.partner.com
• 네트워크 경로/지연:
  • mtr -rw example.com
  • traceroute example.com
• 소켓/FD 상태:
  • ss -s, ss -lntp
  • lsof -p | wc -l
• 로그:
  • tail -f /var/log/nginx/error.log
  • journalctl -u nginx -f
  • kubectl logs deploy/app -f
• 패킷 캡처:
  • tcpdump -i any host app and port 8080
• 부하 테스트:
  • wrk -t4 -c128 -d30s https://example.com/api
  • k6 run script.js

사례 연구: Nginx → Gunicorn → PostgreSQL에서의 504

상황:

• 피크 타임에 /search 엔드포인트에서 504 증가.
• Nginx error.log: upstream timed out (110: Connection timed out) while reading response header from upstream
• APM: /search의 p99 65s, DB 쿼리 중 “LIKE '%keyword%'” 풀스캔.

조치:

1. 즉시 완화

• Nginx proxy_read_timeout을 60→75로 소폭 상향(폭발 방지선 넘지 않게).
• 캐시 가능한 인기 검색어 결과를 Redis에 1분 캐싱.
• 트래픽 분산을 위해 오토스케일 아웃.

2. 근본 해결

• trigram 인덱스/Full Text Search 전환으로 쿼리 2.5s → 120ms로 단축.
• 결과 페이지네이션과 최대 결과 제한.
• Gunicorn 워커 수/타임아웃 재조정(timeout 60, keepalive 5).
• Nginx upstream keepalive 도입으로 커넥션 재사용.

결과:

• 504 전무, p95 180ms, p99 450ms.
• proxy_read_timeout을 45s로 다시 낮춰 방어선 정비.

체크리스트: 배포 전/후

• 프록시/로드밸런서/애플리케이션/DB 타임아웃 매트릭스 작성
  • 각 구간의 타임아웃이 전체 데드라인보다 짧고, 논리적으로 일치하는지 확인.
• 슬로우 쿼리/핫 엔드포인트에 대한 p95/p99 지표 대시보드 준비.
• 트레이스 ID 상관관계 로깅 구현.
• 외부 API 호출에 타임아웃/재시도/서킷 브레이커/폴백 구성.
• 캐시 레이어와 TTL 설계, 캐시 스톰 방지 기법 적용.
• readiness/liveness 프로브로 느린 인스턴스 격리.
• 카나리/블루그린 배포로 위험 분산.
• 장애 대응 Runbook와 롤백 절차 문서화, 온콜 훈련.

자주 하는 실수와 선제적 경고

• 타임아웃을 무조건 늘리기: 단기 완화는 가능하지만 리소스 고갈과 꼬리 지연 악화를 초래.
• 재시도 남발: 다운스트림을 더 압박, 장애를 증폭시킴.
• p50만 보는 모니터링: 504는 주로 긴 꼬리(p95/p99)에서 터진다.
• 단일 병목 무시: 외부 API 하나가 전체 요청을 붙잡는 설계는 위험. 폴백/격벽(Bulkhead) 필수.
• 로그에 타이밍 정보 부재: rt/urt/ust 같은 힌트 없이는 분석 시간이 배로 든다.

실용적인 설정 예시 모음

Nginx + Node.js + Redis

# nginx.conf 일부
http {
  upstream app {
    server app1:3000;
    server app2:3000;
    keepalive 64;
  }

  server {
    listen 80;
    proxy_connect_timeout 3s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    location /api/ {
      proxy_pass http://app;
      proxy_http_version 1.1;
      proxy_set_header Connection "";
      proxy_set_header X-Request-ID $request_id;
    }
  }
}

Node.js 외부 API 호출:

const axios = require('axios');
const client = axios.create({
  timeout: 2500, // 전체 요청 타임아웃
});

async function callPartner(id, signal) {
  try {
    const res = await client.get(`https://partner/api/${id}`, { signal });
    return res.data;
  } catch (e) {
    // 폴백 또는 서킷브레이커 트립
    throw e;
  }
}

PostgreSQL 보호 설정

SET statement_timeout = '2s';
SET lock_timeout = '500ms';

애플리케이션에서도 DB 호출 컨텍스트에 2초 데드라인을 설정해 타임아웃을 전파합니다.

2026 업데이트: 최신 환경에서의 504

서버리스·플랫폼의 ‘하드 타임아웃’을 먼저 확인하라

매니지드 플랫폼은 사용자가 늘릴 수 없는 고정 상한이 있습니다. 504의 원인이 여기일 때가 많습니다.

• AWS API Gateway(REST): 통합 타임아웃 상한이 있으며(기본 29초, 상향 가능하나 한도 존재) 이를 넘는 동기 요청은 504.
• Vercel/Netlify Functions, Cloudflare Workers: 함수 실행 시간 제한(플랜별 수십 초~). 장시간 작업에 부적합.
• Cloud Run / App Runner: 요청 타임아웃을 설정 가능하나 상한 존재.
• 교훈: 긴 작업을 동기 HTTP로 처리하지 말고, 플랫폼 한도 아래로 응답 시간을 설계하세요.

장시간 작업은 비동기로 전환(202 패턴)

타임아웃을 늘리는 대신, 즉시 접수하고 백그라운드에서 처리하는 패턴이 표준입니다.

POST /reports        -> 202 Accepted { "job_id": "abc", "status_url": "/jobs/abc" }
GET  /jobs/abc       -> 200 { "status": "processing" }  (폴링)
GET  /jobs/abc       -> 200 { "status": "done", "result_url": "..." }

• 작업 큐(SQS·Redis·RabbitMQ) + 워커, 완료는 폴링/웹소켓/웹훅으로 통지.
• 사용자 경험: 진행률 표시 + 결과 알림. 게이트웨이 타임아웃에서 자유로워집니다.

LLM·AI 추론 백엔드의 504(신규 단골)

토큰 생성형 응답은 수십 초가 걸려 504를 유발하기 쉽습니다.

• 스트리밍(SSE)으로 첫 바이트를 빨리 전송: 프록시의 proxy_read_timeout은 첫 응답까지의 시간 기준이 흔하므로, 스트리밍은 504를 크게 줄입니다. 단 proxy_buffering off 필요.
• 매우 긴 생성은 비동기 잡 + 폴링/웹훅으로.
• 게이트웨이·엣지·앱의 타임아웃이 스트리밍 지속시간보다 길도록 정렬.

타임아웃 ‘예산’을 분산 트레이싱으로 검증

원문의 타임아웃 예산화 개념을, 이제 OpenTelemetry 트레이스로 실측 검증하세요. 각 스팬(앱→DB→외부 API)의 p95 지연을 합산해 전체 예산을 초과하는 구간을 데이터로 찾아냅니다.

자주 묻는 질문 (FAQ)

Q. 504와 502는 어떻게 다른가요? 504는 업스트림이 제때 응답하지 않아 시간이 초과된 경우(지연), 502는 업스트림이 잘못된 응답이나 끊긴 연결을 준 경우입니다. 504는 “느림”, 502는 “이상”입니다.

Q. 프록시 타임아웃만 늘리면 해결되나요? 근본 해결이 아닙니다. 한계를 잠시 미룰 뿐이고, 사용자는 그만큼 더 오래 기다립니다. 느린 쿼리/연산/의존성을 개선하거나 작업을 비동기화하는 것이 정답입니다. 타임아웃 조정은 보조 수단입니다.

Q. 리포트 생성·대량 처리처럼 원래 오래 걸리는 작업은요? 동기 HTTP로 처리하지 말고 202 Accepted + 작업 큐 + 상태 조회 패턴으로 바꾸세요. 게이트웨이 타임아웃과 무관하게 안정적으로 동작합니다.

Q. 모든 타임아웃을 어떤 값으로 맞춰야 하나요? “가까운 곳은 짧게, 멀수록 약간 넉넉히”가 원칙입니다. 단, 바깥 계층(LB/프록시)의 타임아웃이 안쪽(앱)보다 길어야 중간에서 끊겨 504가 나는 일을 막습니다. 실제 p95 지연을 측정해 역산하세요.

Q. 504가 SEO에 영향을 주나요? 지속적인 504는 크롤링 실패로 이어져 색인에 부정적입니다. 일시적이면 영향이 작지만, 느린 페이지는 Core Web Vitals에도 불리하므로 응답 시간 자체를 개선하는 것이 좋습니다.

결론: 504는 설계와 운영의 아키텍처 신호

504 Gateway Timeout은 단순 에러가 아니라, 시스템의 지연 예산과 설계상의 균열을 알려주는 경고입니다. 즉각적인 복구는 다음을 기본으로 합니다:

• 어디서 지연되는지 로그/지표/트레이스로 빠르게 좁히기
• 단기 완화(캐시, 스케일, 타임아웃 조정)로 피해 최소화
• 근본 원인(느린 쿼리, 블로킹 코드, 외부 의존성)을 제거

재발 방지는 다음을 체계화해야 합니다:

• 타임아웃/재시도의 예산화와 전파
• 비동기/큐 기반 아키텍처로 장기 작업 오프로드
• 캐시, 백프레셔, 서킷 브레이커, 레이트 리미팅
• p95/p99 중심의 관찰 가능성 확보

이 가이드를 팀의 Runbook과 체크리스트로 흡수하면, 다음 504는 더 빨리, 더 안전하게 지나갈 것입니다. 무엇보다 “타임아웃은 설계의 일부”라는 원칙을 시스템 전반에 녹여두는 것이 가장 강력한 예방책입니다.