502 Bad Gateway

502 Bad Gateway는 인터넷이 건네는 한마디입니다: "내 탓하지 마세요—내 뒤에 있는 서버를 탓하세요."

502를 보게 되면, 여러분이 접속한 서버(게이트웨이)는 멀쩡히 작동하고 있습니다. 이 서버는 요청을 받았고, 다른 서버로 전달하려 했으나, 쓸모없는 응답—또는 아무것도 받지 못했습니다. 게이트웨이는 그저 다른 누군가의 나쁜 소식을 전하는 전령일 뿐입니다.

실제로 무슨 일이 일어나고 있는가

현대 웹 인프라에서 단일 서버 하나가 모든 걸 처리하는 경우는 거의 없습니다. 요청은 보통 여러 레이어를 거칩니다:

사용자 → 로드 밸런서 → 애플리케이션 서버 → 데이터베이스

502는 이 중간 서버 중 하나(게이트웨이)가 그 뒤에 있는 서버(업스트림)로부터 유효한 응답을 받지 못할 때 발생합니다. 게이트웨이는 시도했습니다. 실패했습니다. 그 사실을 알려주고 있는 것입니다.

HTTP/1.1 502 Bad Gateway

그게 전부입니다. 장황한 설명 없이—그저 연결 사슬이 어딘가에서 끊어졌다는 것을 인정하는 것입니다.

업스트림이 실패하는 이유

업스트림이 죽었습니다. 애플리케이션 서버가 실행 중이었고, 전달된 요청을 받았으나, 응답 도중에 죽어버렸습니다. 게이트웨이는 절반짜리 응답이나 연결 재설정을 받았습니다.

업스트림이 실행되지 않습니다. 누군가 잘못된 코드를 배포했거나, 프로세스가 메모리를 다 소진했거나, 서버가 재부팅되었습니다. 게이트웨이가 연결을 시도하지만 아무도 없습니다.

업스트림이 횡설수설한 응답을 보내고 있습니다. 서버가 응답하긴 했지만 유효한 HTTP가 아닙니다. 소켓에 스택 트레이스를 직접 뱉었을 수도 있습니다. 잘못 설정된 프록시가 JSON이 와야 할 자리에 HTML을 보냈을 수도 있습니다. 게이트웨이가 이해할 수 없는 것입니다.

연결이 거부되었습니다. 업스트림 서버는 존재하지만 예상된 포트가 열려 있지 않습니다. 게이트웨이가 3000번 포트를 두드리지만, 아무도 거기 없습니다.

네트워크 문제. 방화벽, DNS 장애, 또는 네트워크 파티션으로 인해 게이트웨이가 업스트림에 전혀 닿지 못합니다.

502 vs. 다른 5xx 오류

이것들은 자주 혼동됩니다. 차이는 이렇습니다:

500 Internal Server Error: 여러분이 접속한 서버 자체가 문제입니다. 그 서버 스스로의 잘못입니다.

502 Bad Gateway: 여러분이 접속한 서버는 멀쩡하지만, 그 뒤에 있는 서버가 문제이거나 이상한 응답을 보냈습니다.

503 Service Unavailable: 서버가 의도적으로 요청을 거부하고 있습니다—보통 과부하 상태이거나 점검 중이기 때문입니다. 고장이 아니라 의도된 상태입니다.

504 Gateway Timeout: 게이트웨이 뒤의 서버가 제 시간 안에 응답하지 않았습니다. 502는 엉터리 응답을 받은 것이고, 504는 아무 응답도 받지 못한 것입니다.

502와 504의 차이는 누군가가 횡설수설하는 것과 아예 입을 다물고 있는 것의 차이입니다.

문제 찾기

502를 보게 되면, 게이트웨이는 괜찮습니다. 그 뒤를 살펴보세요.

업스트림이 실행 중인가?

systemctl status your-app-service
netstat -tulpn | grep :3000

서비스가 내려가 있거나 포트가 열려 있지 않다면, 원인을 찾은 것입니다.

업스트림에 직접 접근할 수 있는가?

curl -v http://localhost:3000/health

이것이 작동하는데 게이트웨이가 502를 반환한다면, 문제는 게이트웨이 설정에 있습니다—포트, 호스트명, 또는 프로토콜이 잘못 지정된 것입니다.

로그에는 무엇이 있는가?

게이트웨이 로그에서 무엇이 잘못되었는지 확인하세요:

tail -f /var/log/nginx/error.log

자주 등장하는 메시지:

• upstream prematurely closed connection — 업스트림이 응답 도중에 죽었습니다
• no live upstreams — 모든 백엔드 서버가 실패 상태로 표시되었습니다
• upstream sent invalid header — 응답이 유효한 HTTP가 아니었습니다

애플리케이션 로그에서는 업스트림이 왜 실패했는지 확인하세요:

tail -f /var/log/your-app/app.log

충돌, 메모리 부족 오류, 또는 처리되지 않은 예외를 찾으세요.

연결을 막는 것이 있는가?

telnet backend-server 3000
nc -zv backend-server 3000

이것이 실패한다면, 방화벽과 네트워크 설정을 확인하세요.

502 오류 예방하기

여러 업스트림 운영하기

백엔드 서버가 하나뿐이라면 단일 장애점이 됩니다:

upstream backend {
    server backend1.example.com:3000;
    server backend2.example.com:3000;
    server backend3.example.com:3000;
}

하나가 죽으면, 게이트웨이가 다른 서버로 라우팅합니다.

헬스 체크 설정하기

죽은 서버에 트래픽을 보내지 마세요:

upstream backend {
    server backend1.example.com:3000 max_fails=3 fail_timeout=30s;
    server backend2.example.com:3000 max_fails=3 fail_timeout=30s;
}

3번 실패하면 해당 서버는 30초 동안 비활성 상태로 표시됩니다.

자동 페일오버 활성화하기

location /api {
    proxy_pass http://backend;
    proxy_next_upstream error timeout http_502;
    proxy_next_upstream_tries 2;
}

첫 번째 업스트림이 502를 반환하면, 자동으로 다음 서버를 시도합니다.

적절한 타임아웃 설정하기

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

너무 짧으면 응답이 느린 경우에 불필요한 502가 발생합니다. 너무 길면 사용자가 한없이 기다리게 됩니다.

클라이언트 입장에서 502 처리하기

502 오류는 종종 일시적입니다—서버가 재시작 중이거나, 잠깐의 네트워크 문제일 수 있습니다. 지수 백오프로 재시도하세요:

async function fetchWithRetry(url, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        const response = await fetch(url);
        
        if (response.status === 502 && attempt < maxRetries - 1) {
            const waitTime = Math.pow(2, attempt) * 1000;
            await new Promise(resolve => setTimeout(resolve, waitTime));
            continue;
        }
        
        return response;
    }
}

1초, 2초, 4초 순으로 기다립니다. 대부분의 경우 문제가 저절로 해결됩니다.

핵심 정리

502 Bad Gateway는 게이트웨이의 잘못이 아닙니다. 게이트웨이는 올바르게 작동하고 있습니다—그 뒤에 있는 무언가가 작동하지 않는다고 알려주고 있는 것입니다. 502를 보게 되면, 전령이 아닌 진짜 문제를 찾으세요: 죽어버린 애플리케이션 서버, 네트워크 파티션, 또는 유효한 HTTP 대신 엉터리를 반환하는 백엔드.

게이트웨이는 그저 자신의 임무를 다하고 있을 뿐입니다: 뒤에 있는 서버가 실패했다는 것을 충실하게 보고하는 것입니다.

502 Bad Gateway 자주 묻는 질문

502 오류가 가끔씩만 나타나는 이유는 뭔가요?

여러 백엔드 서버 중 하나만 문제라면, 로드 밸런서가 해당 서버로 요청을 보낼 때만 간헐적으로 502가 나타납니다. 하나가 아닌 모든 업스트림의 상태를 확인하세요.

502가 보일 때 페이지를 새로고침하면 되나요?

네. 502 오류는 종종 일시적입니다—서버가 재시작 중이거나 순간적인 네트워크 문제일 수 있습니다. 몇 초 기다렸다가 새로고침하면 대부분 해결됩니다. 계속 나타난다면, 더 심각한 문제가 있는 것입니다.

502와 사이트가 "다운"된 것은 어떻게 다른가요?

사이트가 완전히 다운되면, 보통 연결 자체가 안 됩니다—브라우저가 계속 로딩 중이거나 "연결 거부"를 표시합니다. 502는 무언가(게이트웨이)에는 접속되었지만, 그 뒤의 서버들이 작동하지 않는다는 것을 의미합니다. 현관문은 열려 있는데, 그 뒤의 건물이 불타고 있는 것입니다.

502가 내 브라우저나 인터넷 연결 때문에 생길 수도 있나요?

거의 없습니다. 502는 브라우저가 아닌 서버에서 생성됩니다. 502가 보인다면, 문제는 거의 확실히 서버 측에 있습니다. 다만, 네트워크에 잘못 설정된 프록시가 있다면 이론적으로는 발생할 수 있습니다.

잘 작동하는 줄 알았던 웹사이트에서 CDN이 502를 보여주는 이유는 뭔가요?

CDN은 인터넷에는 연결되어 있지만, 해당 웹사이트의 특정 오리진 서버에는 닿지 못하는 것입니다. 직접 접속하는 사람들에게는 사이트가 정상적으로 보일 수 있지만, CDN에서 오리진으로 가는 경로가 끊어진 상태입니다—방화벽 규칙, DNS 문제, 또는 오리진 서버가 CDN의 IP 주소를 차단하고 있기 때문인 경우가 많습니다.