Service Unavailable

개요

503 Service Unavailable는 서버가 과부하나 유지보수 때문에 일시적으로 요청을 처리할 수 없다는 뜻입니다. 서버 자체는 살아 있지만 지금은 요청을 받을 수 없는, 의도적이거나 일시적인 상태를 나타냅니다.

잘 설계된 503 응답은 Retry-After 헤더로 언제 다시 시도하면 되는지 알려줍니다. 계획된 배포·점검 시에는 사용자에게 정상적인 '점검 중' 페이지를 보여주는 용도로도 쓰입니다.

언제 발생하나

• 트래픽 급증으로 서버가 과부하되어 워커가 고갈됐을 때
• 계획된 점검(maintenance) 시간 동안 서비스를 내렸을 때
• 오토스케일러가 아직 용량을 늘리는 중일 때
• 의존 서비스 장애로 헬스체크가 실패해 인스턴스를 제외했을 때

요청 / 응답 예시

GET / HTTP/1.1
Host: www.example.com

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/html

<h1>503 Service Unavailable</h1>
<p>We are down for maintenance. Please try again shortly.</p>

코드로 보기

app.use((req, res, next) => {
  if (process.env.MAINTENANCE === '1') {
    return res.status(503).set('Retry-After', '120').send('Under maintenance');
  }
  next();
});

location / {
  if (-f /etc/nginx/maintenance.on) {
    return 503;
  }
  proxy_pass http://backend;
}
error_page 503 /maintenance.html;

실무 참고

• 503은 일시적 오류이므로 재시도가 유효합니다. Retry-After를 존중해 서버가 회복할 시간을 주세요.
• 점검용 503을 낼 때는 검색엔진이 페이지를 삭제하지 않도록 Retry-After를 주고, 오래 지속하지 마세요.
• 503(서버가 스스로 못 받음)과 502/504(백엔드 응답 문제/지연)는 원인이 다릅니다. Retry-After가 있으면 대개 503 계열입니다.

관련 상태코드

관련 헤더

스펙 근거