HTTPTools

HTTP 502 Bad Gateway

중간자의 항의: 프록시나 CDN이 실제 서버에 요청했지만 잘못된 응답을 받았거나 아무 응답도 받지 못했습니다.

HTTP 502의 의미

HTTP 502 Bad Gateway는 nginx, 로드 밸런서, Cloudflare와 같은 중개자가 요청을 업스트림 서버로 전달했지만 연결 거부, 응답 중 크래시, HTTP로 파싱되지 않는 바이트 등 유효하지 않은 응답을 받았을 때 발생합니다.

지목된 대상은 거의 항상 프록시 자체가 아닙니다. 실제 원인은 그 뒤에 있는 애플리케이션 서버가 다운되었거나, 과부하 상태이거나, 접근할 수 없는 상태라는 것입니다.

502 오류의 일반적인 원인

  • 애플리케이션 서버(PHP-FPM, Node, gunicorn 등)가 크래시되었거나 실행되고 있지 않습니다.
  • 프록시가 잘못된 포트/소켓을 가리키고 있거나, 방화벽이 업스트림 연결을 차단하고 있습니다.
  • 업스트림 응답이 버퍼를 초과했거나 전송 도중 타임아웃이 발생했습니다.
  • 트래픽이 흐르는 중에 배포로 인해 백엔드가 재시작되었습니다.
  • Cloudflare 같은 CDN을 사용하는 경우: 엣지는 정상이지만 오리진 서버가 다운된 상태입니다.

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

  • 1분 정도 후에 새로고침하세요 — 배포 중 발생한 502는 저절로 해결됩니다.
  • 계속 발생한다면 서비스의 상태 페이지를 확인하세요.

개발자로서 해결하는 방법

  • 업스트림 프로세스가 살아 있고 프록시가 기대하는 주소에서 리스닝 중인지 확인하세요.
  • 프록시의 오류 로그를 확인하세요 — nginx는 정확한 원인을 알려줍니다(connect() 실패, upstream prematurely closed 등).
  • 프록시와 애플리케이션 사이의 포트, 유닉스 소켓 경로, 방화벽 규칙을 확인하세요.
  • 로드 밸런서가 죽은 인스턴스로 라우팅하지 않도록 헬스 체크를 추가하세요.

응답 예시

HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html

<html><body><h1>502 Bad Gateway</h1></body></html>

자주 묻는 질문

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

502는 업스트림이 유효하지 않은 응답을 보냈거나(또는 연결을 거부했음을), 504는 타임아웃 내에 아예 응답하지 않았음을 의미합니다.

Cloudflare에서 왜 502가 표시되나요?

Cloudflare 엣지가 오리진 서버로부터 유효한 응답을 받지 못했습니다 — 오리진이 다운되었거나, 접근할 수 없거나, 잘못된 형식의 응답을 반환하고 있습니다.

502는 일시적인 오류인가요?

대개는 그렇습니다 — 배포와 재시작으로 인해 잠시 502가 발생할 수 있습니다. 502가 지속된다면 백엔드가 실제로 다운되었거나 잘못 구성된 것입니다.