1. 라이브러리
  2. HTTP와 웹
  3. HTTP 상태 코드

503 Service Unavailable

업데이트됨 1개월 전

503 Service Unavailable 오류는 HTTP 상태 코드 중에서 진정으로 낙관적인 몇 안 되는 코드입니다. "무언가 잘못되었다"고 말하지 않습니다. "무언가 일시적으로 잘못되었는데, 나는 그걸 알고 있고, 언제 다시 시도하면 되는지도 알려줄게"라고 말합니다.

실패를 대하는 방식이 근본적으로 다릅니다.

503의 약속

503은 서버와 클라이언트 간의 계약입니다:

  1. 서버가 요청을 받고 이해했습니다
  2. 지금 당장은 처리할 수 없습니다
  3. 이건 일시적인 상황입니다
  4. 언제 다시 오면 되는지 알려드립니다
HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Type: application/json

{
    "error": "Service Unavailable",
    "message": "We're performing scheduled maintenance. Service resumes in 1 hour.",
    "retryAfter": 3600
}

Retry-After 헤더는 그 약속을 구체적인 형태로 만듭니다. 없으면 503은 그냥 불평입니다. 있으면 503은 하나의 계획이 됩니다.

서버가 요청을 미룰 때

예정된 점검

503의 가장 솔직한 활용 — 의도적으로 서비스를 중단하는 경우입니다:

HTTP/1.1 503 Service Unavailable
Retry-After: Wed, 21 Oct 2024 16:00:00 GMT

{
    "error": "Maintenance in Progress",
    "message": "Scheduled maintenance until 4:00 PM.",
    "resumeTime": "2024-10-21T16:00:00Z"
}

과부하

서버가 요청에 압도되는 경우:

HTTP/1.1 503 Service Unavailable
Retry-After: 30

{
    "error": "Service Overloaded",
    "message": "Too many concurrent requests. Try again in 30 seconds."
}

의존성 장애

중요한 의존 서비스(데이터베이스, 캐시, 외부 API)가 다운된 경우:

app.get('/api/data', async function(request, response) {
    try {
        const data = await database.query('SELECT * FROM data');
        response.json(data);
    }
    catch(error) {
        response.status(503)
            .set('Retry-After', '60')
            .json({
                error: 'Service Unavailable',
                message: 'Database temporarily unavailable'
            });
    }
});

시작과 종료

애플리케이션이 아직 준비되지 않았거나, 정상적으로 종료 중인 경우:

let ready = false;
let shuttingDown = false;

app.use(function(request, response, next) {
    if(!ready || shuttingDown) {
        return response.status(503).json({
            error: ready ? 'Shutting Down' : 'Starting Up',
            message: 'Service temporarily unavailable'
        });
    }
    next();
});

Retry-After 헤더

이 헤더는 503을 단순한 상태 코드에서 대화로 바꿉니다.

짧은 대기를 위한 초 형식:

Retry-After: 60

예정된 점검을 위한 날짜 형식:

Retry-After: Wed, 21 Oct 2024 16:00:00 GMT

Retry-After 없이는 클라이언트가 추측에 의존할 수밖에 없습니다. 있으면 언제 돌아와야 할지 정확히 알 수 있습니다.

점검 모드 구현하기

가장 간단한 방법 — 파일이 있거나 없거나:

const fs = require('fs');

app.use(function(request, response, next) {
    if(fs.existsSync('/var/www/maintenance.flag')) {
        const config = JSON.parse(fs.readFileSync('/var/www/maintenance.flag'));
        return response.status(503)
            .set('Retry-After', config.retryAfter)
            .json({
                error: 'Maintenance in Progress',
                message: config.message
            });
    }
    next();
});

점검 활성화:

echo '{"retryAfter": 3600, "message": "Scheduled maintenance"}' > /var/www/maintenance.flag

비활성화:

rm /var/www/maintenance.flag

배포도 필요 없고, 재시작도 필요 없습니다.

약속을 지키는 클라이언트

503과 Retry-After를 존중하는 클라이언트:

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

        if(response.status !== 503) {
            return response;
        }

        const retryAfter = response.headers.get('Retry-After');
        let waitTime;

        if(retryAfter && /^\d+$/.test(retryAfter)) {
            waitTime = parseInt(retryAfter) * 1000;
        }
        else if(retryAfter) {
            waitTime = new Date(retryAfter).getTime() - Date.now();
        }
        else {
            waitTime = Math.pow(2, attempt) * 1000; // 지수 백오프
        }

        await new Promise(function(resolve) {
            setTimeout(resolve, waitTime);
        });
    }

    throw new Error('Service unavailable after retries');
}

의미 있는 헬스 체크

헬스 엔드포인트는 상태가 비정상일 때 503을 반환해야 합니다:

app.get('/health', async function(request, response) {
    const checks = {
        database: await pingDatabase(),
        cache: await pingCache()
    };

    const healthy = Object.values(checks).every(Boolean);

    response.status(healthy ? 200 : 503)
        .set(healthy ? {} : { 'Retry-After': '60' })
        .json({ status: healthy ? 'healthy' : 'unhealthy', checks });
});

로드 밸런서는 이 엔드포인트를 감시합니다. 503을 감지하면 서버가 복구될 때까지 트래픽을 다른 곳으로 라우팅합니다.

503과 주변 상태 코드들

상태 코드의미재시도?
500예상치 못한 오류 발생아마 불가
502업스트림 서버 비정상 응답불명확
503일시적으로 사용 불가예, Retry-After 시점에
429속도 제한 초과예, 서버는 정상

503은 독특합니다. 서버가 일시적인 약점을 솔직히 인정하면서도 회복을 약속합니다. 500은 혼란입니다. 502는 책임 전가입니다. 429는 클라이언트의 잘못입니다. 오직 503만이 "이건 내 문제고, 내가 해결하고 있어"라고 말합니다.

503 활용 원칙

항상 Retry-After를 포함하세요. Retry-After 없는 503은 기한 없는 약속입니다.

일시적인 상태에만 사용하세요. 데이터베이스 스키마가 잘못된 건 500입니다. 데이터베이스가 재시작 중이라면 503입니다.

빠르게 실패하세요. 요청을 처리할 수 없다는 걸 안다면, 즉시 503을 반환하세요. 이미 알고 있는 걸 다시 발견하느라 리소스를 낭비하지 마세요.

503 발생 빈도를 모니터링하세요. 잦은 503은 용량 문제, 불안정한 의존 서비스, 또는 너무 오래 걸리는 점검 프로세스를 드러냅니다.

503 Service Unavailable 자주 묻는 질문

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

500은 예상치 못한 오류가 발생했다는 의미입니다 — 버그, 처리되지 않은 예외, 손상된 상태. 서버는 언제, 혹은 회복될 수 있을지조차 모릅니다. 503은 서버가 일시적으로 사용 불가능하다는 것을 스스로 알고 있으며, 회복을 예상한다는 의미입니다. 문제를 이해하고 일시적인 경우라면 503을, 그렇지 않으면 500을 사용하세요.

503에 항상 Retry-After를 포함해야 하나요?

예. Retry-After 없이는 클라이언트가 재시도 시점을 추측해야 하고, 그러면 공격적인 폴링(복구 중인 서버에 과부하)이나 너무 이른 포기로 이어집니다. Retry-After는 막연한 "나중에 다시 시도하세요"를 구체적인 계약으로 바꿔줍니다.

속도 제한에서 503과 429를 언제 써야 하나요?

429는 "당신이 설정된 한도에 도달했지만, 서버는 정상입니다"를 의미합니다. 503은 "서버가 지금 누구의 요청도 처리할 수 없습니다"를 의미합니다. 클라이언트별 속도 제한에는 429를, 서버가 실제로 과부하 상태여서 어떤 클라이언트도 서비스할 수 없을 때는 503을 사용하세요.

로드 밸런서는 503을 어떻게 활용하나요?

대부분의 로드 밸런서는 헬스 엔드포인트를 모니터링합니다. 서버가 503을 반환하면 로드 밸런서는 해당 서버를 비정상으로 표시하고 트래픽 라우팅을 중단합니다. 서버가 다시 200을 반환하기 시작하면 트래픽이 재개됩니다. 이 자동 장애 조치가 바로 고가용성에서 503이 중요한 이유입니다.

이전

201 Created

다음

200 OK

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

😔
🤨
😃