500 내부 서버 오류

업데이트됨 1개월 전

500 내부 서버 오류를 마주했을 때, 마치 막막한 벽에 부딪힌 것과 같습니다. 서버가 "내 쪽에서 뭔가 잘못됐어"라고만 할 뿐—그게 전부입니다. 실제로 무엇이 잘못됐는지 아무런 정보도 없기 때문에, 가장 답답한 오류가 바로 이것입니다.

이건 의도된 설계입니다. 500은 일종의 만능 오류 코드입니다. 서버가 예상치 못한 상황을 만났을 때—처리되지 않은 예외, 다운된 데이터베이스, 있어서는 안 될 곳의 null 값—더 구체적인 오류를 반환할 수 없다면, 기본값으로 500을 돌려보냅니다. 당신이 보는 오류는 실제로 발생한 오류가 아닙니다.

서버가 실제로 하는 말

500 응답의 의미:

서버가 요청을 받았다
요청은 유효해 보였다
처리 중 예상치 못한 일이 발생했다
서버는 무슨 일인지 알려주지 않을 것이다

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "error": "Internal Server Error",
    "message": "An unexpected error occurred"
}

이건 거의 아무것도 알려주지 않습니다. 의도적으로 그렇게 설계된 겁니다. 운영 환경에서 서버는 실패를 숨깁니다. 노출하면 보안 위험이 되기 때문입니다. 실제 오류—스택 추적, 데이터베이스 타임아웃, 널 포인터—는 응답이 아닌 로그에 있습니다.

실제로 무엇이 고장나는가

처리되지 않은 예외

가장 흔한 원인입니다. 코드가 아무도 잡지 않는 오류를 던집니다:

app.get('/api/users/:id', async function(request, response) {
    // 이 코드가 오류를 던지면 catch가 없으니—곧바로 500으로
    const user = await database.findUser(request.params.id);
    response.json(user);
});

데이터베이스 장애

데이터베이스가 다운되거나, 연결 풀이 소진되거나, 쿼리가 잘못 작성된 경우:

// 연결 거부, 쿼리 타임아웃, 문법 오류—모두 500이 된다
const data = await database.query('SELECT * FROM users');

설정 오류

누락된 환경 변수, 잘못 설정된 서비스 URL:

const apiKey = process.env.API_KEY; // undefined
await externalService.fetch(apiKey); // 이유를 알 수 없는 실패

리소스 고갈

서버의 메모리, 디스크 공간, 또는 데이터베이스 연결이 부족해진 경우. 깔끔한 스택 추적을 남기지 않는 경우가 많아 디버깅하기 가장 까다롭습니다.

널 참조

전형적인 사례:

const user = getUser(id);
response.json({ name: user.name.toUpperCase() }); // user가 null

운영 환경과 개발 환경에서의 오류 응답

500은 보는 사람에 따라 다른 내용을 보여줘야 합니다.

운영 환경 (사용자가 보는 것):

{
    "error": "Internal Server Error",
    "message": "An unexpected error occurred",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

개발 환경 (개발자가 보는 것):

{
    "error": "TypeError",
    "message": "Cannot read property 'name' of null",
    "stack": "TypeError: Cannot read property 'name' of null\n    at /app/routes/users.js:15:32",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

요청 ID가 핵심입니다. 사용자에게 전달되는 무의미한 오류 메시지와 로그에 있는 실제 오류를 이어주는 다리입니다. 사용자가 "오류가 났어요"라고 신고하면, 그 ID 하나로 정확히 무슨 일이 일어났는지 찾아낼 수 있습니다.

오류를 빠짐없이 잡아라

목표는 단순합니다: 어떤 오류도 처리되지 않은 채 500으로 흘러나가서는 안 됩니다.

// 개별 라우트를 감싸기
app.get('/api/data', async function(request, response) {
    try {
        const data = await fetchData();
        response.json(data);
    }
    catch(error) {
        logger.error('데이터 가져오기 실패', { error, requestId: request.id });
        response.status(500).json({
            error: '데이터 가져오기 실패',
            requestId: request.id
        });
    }
});

// 전역 핸들러가 나머지를 모두 잡는다
app.use(function(error, request, response, next) {
    logger.error({
        requestId: request.id,
        url: request.url,
        method: request.method,
        error: error.message,
        stack: error.stack
    });

    response.status(500).json({
        error: 'Internal Server Error',
        requestId: request.id
    });
});

클라이언트가 해야 할 일

500은 일시적일 수 있습니다—순간적인 데이터베이스 문제, 잠깐의 리소스 급증. 지수 백오프를 적용하여 재시도하세요:

async function fetchWithRetry(url, maxRetries = 3) {
    for(let attempt = 0; attempt < maxRetries; attempt++) {
        const response = await fetch(url);

        if(response.status >= 500 && attempt < maxRetries - 1) {
            // 매번 더 오래 기다린다: 1초, 2초, 4초
            await sleep(Math.pow(2, attempt) * 1000);
            continue;
        }

        return response;
    }
}

그리고 사용자가 이해할 수 있는 메시지를 보여주세요:

if(response.status === 500) {
    const error = await response.json();
    showError(
        '저희 쪽에서 문제가 발생했습니다. 다시 시도해 주세요.',
        `참조 번호: ${error.requestId}`
    );
}

실제 오류 찾기

500은 증상입니다. 원인은 로그에 있습니다.

# 요청 찾기
grep "550e8400-e29b-41d4-a716" /var/log/app.log

# 최근 오류 찾기
grep -A 20 "Error:" /var/log/app.log | tail -100

패턴을 찾으세요:

시간 기반: 백업 중, 트래픽 최고조 시, 크론 작업이 실행되는 자정에 발생하는 오류
엔드포인트별: 다른 라우트보다 유독 많이 실패하는 특정 라우트
사용자별: 특정 계정이나 데이터가 실패를 유발하는 경우

오류 추적 서비스(Sentry, Rollbar, Bugsnag)를 사용하면 훨씬 수월해집니다—오류를 집계하고, 스택 추적을 보여주고, 발생 빈도를 추적하며, 급증 시 알림을 보냅니다.

다른 5xx 오류들

더 구체적인 코드를 쓸 수 없을 때만 500을 사용하세요:

502 Bad Gateway: 서버가 다른 서버에 요청을 보냈는데 엉뚱한 응답을 받은 경우
503 Service Unavailable: 서버가 일시적으로 과부하 상태이거나 점검 중인 경우
504 Gateway Timeout: 서버가 다른 서버에 요청을 보냈는데 응답이 끝내 오지 않은 경우

이 코드들은 클라이언트에게 더 구체적인 정보를 전달합니다. Retry-After 헤더가 달린 503은 언제 다시 시도해야 할지 알려줍니다. 502는 문제가 업스트림에 있다는 것을, 즉 지금 이 서버가 아닌 다른 곳에 있다는 것을 알려줍니다.

자주 저지르는 실수들

내부 정보를 노출하는 것:

// 위험—데이터베이스 스키마가 드러난다
{"error": "SequelizeDatabaseError: column 'api_key' does not exist"}

오류를 조용히 삼키는 것:

catch(error) {
    // 오류가 허공으로 사라진다—나중에 디버깅할 때 막막해진다
    response.status(500).json({ error: 'Error' });
}

클라이언트 실수에 500을 사용하는 것:

// 잘못된 예: 클라이언트가 잘못된 데이터를 보낸 건 400이다
POST /api/users {"email": "not-an-email"}
HTTP/1.1 500 Internal Server Error

500은 서버 쪽에서 뭔가를 고장냈을 때를 위한 코드입니다. 400번대는 클라이언트 쪽이 잘못했을 때를 위한 겁니다.

500 내부 서버 오류 자주 묻는 질문

500 오류가 무엇이 잘못됐는지 왜 알려주지 않나요?

보안 때문입니다. 자세한 오류 메시지는 데이터베이스 구조, 파일 경로, 사용 중인 라이브러리를 드러낼 수 있습니다—공격자가 충분히 악용할 수 있는 정보입니다. 실제 오류는 로그에 기록되며, 거기서는 당신만 볼 수 있습니다.

500 오류를 재시도해야 하나요?

네, 다만 횟수를 제한해야 합니다. 500 중에는 일시적인 것도 있고(잠깐의 데이터베이스 문제), 지속적인 것도 있습니다(코드의 버그). 점점 간격을 늘려가며 두세 번 재시도해 보세요. 계속 실패한다면 멈추세요—다시 요청한다고 코드 버그가 저절로 고쳐지지는 않습니다.

운영 환경에서 500 오류를 어떻게 디버깅하나요?

요청 ID에서 시작하세요. 모든 500 응답에는 요청 ID가 포함되어 있어야 합니다. 그 ID로 로그를 검색하면 실제 스택 추적을 찾을 수 있습니다. 아직 요청 ID를 쓰고 있지 않다면 지금 바로 도입하세요—운영 환경 오류를 디버깅할 때 이보다 유용한 도구는 없습니다.

500과 502의 차이는 무엇인가요?

500은 이 서버 자체에 문제가 생긴 것입니다. 502는 서버 자체는 멀쩡하지만, 그것이 의존하는 곳(데이터베이스, API, 업스트림 서비스)에서 잘못된 응답이 온 것입니다. 이 구분을 알면 어느 쪽을 살펴봐야 할지 바로 좁힐 수 있습니다.

304 Not Modified

204 No Content

이 페이지가 도움이 되었나요?

😔

🤨

😃