502/504 Gateway Timeout은 왜 발생하나요?

프록시가 업스트림 서버 응답을 제시간에 받지 못하거나, 애플리케이션이 타임아웃보다 오래 걸릴 때 발생합니다.

가장 먼저 무엇을 점검해야 하나요?

문제가 나는 경로를 재현하고 프록시 로그와 백엔드 로그를 같은 시각으로 맞춰 지연 구간을 먼저 찾으세요.

Choorai | 문서

KO EN

런타임/프록시 타임아웃

502/504 Gateway Timeout 해결하기

프록시와 애플리케이션 타임아웃 설정이 어긋나면 502, 504가 반복됩니다.

TL;DR (핵심 요약)

1) 문제 요청 경로/소요시간 측정 2) 프록시 타임아웃과 앱 처리시간 비교 3) 장시간 작업은 비동기 처리로 분리

심각

504 Gateway Timeout

원인

업스트림 서버 응답이 프록시 타임아웃 제한 내에 도착하지 못했습니다.

해결책

문제 엔드포인트의 평균/최대 처리시간 측정
프록시와 런타임 timeout 설정값 정렬
느린 DB 쿼리 및 외부 API 호출 구간 최적화
장시간 작업은 큐 기반 비동기 작업으로 분리

점검 예시

terminal

# 응답 시간 확인
curl -w "status=%{http_code} total=%{time_total}
" -o /dev/null -s https://api.example.com/reports

# 헬스체크 분리
curl -i https://api.example.com/health

nginx.conf

location /api/ {
  proxy_connect_timeout 10s;
  proxy_send_timeout 60s;
  proxy_read_timeout 60s;
}

주의

타임아웃만 무작정 늘리면 장애 감지와 복구가 늦어집니다. 원인 쿼리/외부 연동 지연을 먼저 줄인 뒤 필요한 범위만 조정하세요.

Prerequisites

502/504가 발생하는 요청 경로와 시점을 파악할 수 있어야 합니다.
프록시(Nginx/Cloudflare)와 애플리케이션 서버 로그를 확인할 수 있어야 합니다.
백엔드 타임아웃 설정 값을 점검할 수 있어야 합니다.

Validation

문제 구간 요청이 502/504 대신 2xx/4xx로 안정적으로 응답합니다.
프록시와 앱 서버 타임아웃 값이 일관되게 설정됩니다.
장시간 처리 작업이 비동기 큐 또는 백그라운드 작업으로 분리됩니다.

Troubleshooting

업스트림 서버가 느린 쿼리로 지연되는지 APM/로그로 확인하세요.
Nginx proxy_read_timeout, Cloud Run timeout 설정을 재검토하세요.
동기 처리 대신 작업 큐/웹훅 콜백 모델로 전환을 고려하세요.

References

피드백 보내기

입력한 내용으로 새 이슈 페이지를 엽니다.

GitHub 이슈로 보내기