이 글의 목적은 HTTP 500, 502, 503, 504와 같은 서버 오류의 의미와 원인, 현장 복구 절차, 재발방지 대책을 통합 정리하여 개발·운영·보안 담당자가 즉시 활용할 수 있도록 돕는 것이다.
1. 오류 코드 한눈에 이해하기
| 코드 | 상태 메시지 | 의미 | 주요 원인 | 즉시 조치 |
|---|---|---|---|---|
| 500 | Internal Server Error | 애플리케이션 내부 처리 중 예외가 발생한 상태이다 | 핸들링되지 않은 예외, 템플릿 렌더 실패, 잘못된 환경변수, 라이브러리 충돌이다 | 서버 로그와 APM에서 트레이스ID 기반 원인 함수·쿼리를 식별하고 롤백 또는 핫픽스를 수행한다 |
| 502 | Bad Gateway | 리버스 프록시나 로드밸런서가 업스트림으로부터 유효한 응답을 받지 못한 상태이다 | 업스트림 다운, 헬스체크 실패, Keep-Alive 불일치, 업스트림 포트/프로토콜 오류, TLS 핸드셰이크 실패이다 | 업스트림 프로세스 상태와 포트 바인딩을 확인하고 프록시 타임아웃·버퍼·헤더 크기 설정을 점검한다 |
| 503 | Service Unavailable | 서비스가 일시적으로 처리 불가한 상태이다 | 배포 중 드레이닝 미흡, 스레드·커넥션 풀 고갈, DB·캐시 장애, 과부하·스파이크 트래픽이다 | Auto Scaling 또는 임시 용량 증설, 큐·캐시 복구, Rate Limit 활성화, 유지보수 페이지와 Retry-After 헤더 설정이다 |
| 504 | Gateway Timeout | 프록시가 업스트림 응답을 제한 시간 내 받지 못한 상태이다 | 느린 DB 쿼리, 외부 API 지연, Deadlock, 네트워크 지연, 타임아웃 파라미터 불일치이다 | 지연 구간 트레이싱, 타임아웃 상·하류 정렬, 쿼리 튜닝, 캐싱·CQRS 적용, 서킷브레이커 설정이다 |
2. 15분 복구 체크리스트(공통)
- 장애 범위 확정: 영향 서비스·엔드포인트·리전과 시작 시각을 정의한다.
- 지표 점검: 오류율(5xx), 지연시간, 트래픽, 인프라 리소스(CPU·메모리·FD·스레드)를 확인한다.
- 헬스체크 상태: 로드밸런서·Ingress·프록시의 업스트림 Healthy 수를 확인한다.
- 릴리스 이력: 직전 배포·설정 변경·스키마 변경 여부를 확인한다.
- 우회·격리: 문제 AZ·버전·업스트림을 트래픽에서 제거하고 정상이면 점진 복귀한다.
- 고객 공지: 상태 페이지에 영향 범위와 ETA 없이 진행 상황만 사실대로 게시한다.
3. 역할별 즉시 조치
3.1 운영·SRE
- 프록시 관점에서 502/504 비율과 업스트림별 오류 분포를 확인한다.
- 프록시 버퍼, 헤더 크기, 타임아웃을 상·하류와 일치시킨다.
- ELB/Ingress에서 비정상 Target을 즉시 드레인하고 신규 인스턴스를 기동한다.
3.2 백엔드
- 스레드 풀, 커넥션 풀, 큐 길이, GC 정지 시간을 확인한다.
- 핵심 쿼리 실행 계획을 확인하고 인덱스·제한조건·락 경합을 점검한다.
- 예외 핸들링을 통일하고 에러 응답에 코릴레이션ID를 부여한다.
3.3 보안
- WAF 차단·챌린지 비율 급증 시 오탐 규칙을 점검한다.
- 봇·스크레이핑 스파이크를 레이트리밋과 캐시로 흡수한다.
4. 원인별 심층 대처
4.1 HTTP 500: 애플리케이션 예외
- 핸들링되지 않은 예외를 전역 핸들러에서 4xx/5xx로 구분한다.
- 템플릿·직렬화 오류는 샘플 데이터로 회귀테스트를 추가한다.
- 환경변수 검증을 스타트업 단계에서 실패-빠른 방식으로 강제한다.
- APM에서 슬로우 트랜잭션을 기준으로 N+1, 외부 API 지연을 분리한다.
# 예: Spring Boot 전역 예외
@ControllerAdvice
class GlobalHandler {
@ExceptionHandler(IllegalArgumentException.class)
ResponseEntity<Object> badReq(...) { ... } // 400
@ExceptionHandler(Exception.class)
ResponseEntity<Object> internal(...) { ... } // 500
}
4.2 HTTP 502: 프록시↔업스트림 불일치
- 업스트림 포트·프로토콜(TCP/HTTP/HTTP2, TLS) 정의를 맞춘다.
- 프록시의 헤더 크기와 응답 버퍼를 애플리케이션 최대 응답크기에 맞춘다.
- Keep-Alive, 업스트림 최대 커넥션, 재사용 여부를 일치시킨다.
| 컴포넌트 | 핵심 설정 | 권장 포인트 |
|---|---|---|
| Nginx | proxy_read_timeout, proxy_connect_timeout, proxy_busy_buffers_size | 상류 타임아웃보다 10~20% 크게 설정한다 |
| Apache | ProxyTimeout, Timeout, RequestReadTimeout | 백엔드 KeepAlive와 일치시킨다 |
| 로드밸런서 | Idle Timeout, HealthCheck Path/Interval/Threshold | 애플리케이션 스타트업 시간 대비 여유를 둔다 |
4.3 HTTP 503: 일시적 과부하·유지보수
- 배포 시 드레인과 Readiness Probe를 필수화한다.
- 스레드·커넥션 풀 한도를 단계적으로 상향하고 큐 초과는 즉시 거부한다.
- Retry-After 헤더를 포함해 클라이언트 재시도 정책을 유도한다.
- 캐시 레이어를 활용하여 DB 부하를 우회한다.
# 예: 유지보수 응답
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/html
4.4 HTTP 504: 업스트림 지연
- 상·하류 타임아웃을 체인 전체에서 정렬한다.
- 느린 쿼리는 LIMIT·인덱스·배치 처리로 분할한다.
- 외부 API에는 서킷브레이커, 타임박스, 폴백 응답을 둔다.
- 백그라운드 워크큐로 요청-응답 경로를 단축한다.
5. 진단 절차: 재현 가능한 방법
- 증상 수집: 에러 응답 헤더, 코릴레이션ID, 사용자 구간, 클라이언트 유형을 수집한다.
- 프록시 단계 진단: 동일 요청을 업스트림 직결과 프록시 경유로 각각 호출한다.
- 네트워크 검사: DNS, TLS, 라우팅, 패킷 손실을 확인한다.
- 자원 병목: CPU 스로틀링, GC Stop-The-World, IO 대기, FD·스레드 한도를 측정한다.
- 데이터베이스: 슬로우로그, 락 대기, 연결 수, 레플리카 레이턴시를 확인한다.
# 프록시 경유/직결 비교
curl -i https://api.example.com/v1/orders -H "X-Request-ID: test-1"
curl -i http://upstream1.internal:8080/v1/orders -H "X-Request-ID: test-1"
6. 타임아웃·재시도·서킷브레이커 표준화
| 계층 | 권장 타임아웃 | 재시도 | 비고 |
|---|---|---|---|
| 클라이언트 SDK | 1~3초 | 지수백오프 2~3회, Jitter 적용 | POST는 멱등키 사용한다 |
| API 게이트웨이/프록시 | 클라이언트 타임아웃보다 +20% | 멱등 요청만 재시도 | 헤더 X-Idempotency-Key 도입 |
| 애플리케이션→DB | 쿼리별 500ms~3초 | 재시도 금지 | 타임아웃은 커넥션/쿼리 분리 |
| 애플리케이션→외부 API | SLA 기반 1~5초 | 2회, 서킷브레이커 | 폴백·캐시 사용 |
7. 프록시·웹서버 핵심 설정 점검
Nginx
proxy_connect_timeout 3s;
proxy_send_timeout 5s;
proxy_read_timeout 5s;
proxy_buffers 32 16k;
proxy_busy_buffers_size 64k;
client_max_body_size 10m;
Apache
Timeout 30
ProxyTimeout 10
RequestReadTimeout header=10-20,MinRate=500 body=10,MinRate=500
IIS
<system.webServer>
<security><requestFiltering requestLimits maxAllowedContentLength="10485760"/></security>
<serverRuntime uploadReadAheadSize="49152" enabled="true" />
</system.webServer>
8. 쿠버네티스·클라우드 운영 포인트
- Readiness Probe 실패는 503로 전환되므로 배포 전에 워밍업 엔드포인트를 제공한다.
- Liveness Probe는 재기동만 수행하므로 빈번한 Kill은 콜드스타트를 유발한다.
- HPA는 지연된 반응을 보이므로 요청 큐 길이나 지연시간 기반 스케일 정책을 추가한다.
- Ingress·서비스 타임아웃과 애플리케이션 타임아웃을 일치시킨다.
readinessProbe:
httpGet: { path: /health/ready, port: 8080 }
periodSeconds: 5
failureThreshold: 3
9. 데이터베이스·캐시 병목 해소
- 슬로우 쿼리 기준을 500ms 이하로 설정하고 상위 10개를 지속 튜닝한다.
- 쓰기 폭주 시 큐잉과 배치로 흡수하고 강한 일관성이 불필요한 조회는 캐시로 대체한다.
- 커넥션 풀을 CPU 코어·워크로드에 맞춰 상한을 설정한다.
10. 재발 방지와 설계 개선
- 에러 예산과 SLO를 정의하고 월간 회귀 테스트에 장애 재현 시나리오를 포함한다.
- 그레이스풀 디그레이드 전략을 도입하여 비핵심 기능을 자동 차단한다.
- 피크 트래픽 대비 1.5~2배 용량을 확보하고 캐시 적중률 목표를 설정한다.
- 배포는 블루·그린 또는 카나리로 전환하여 대규모 실패를 방지한다.
11. 현장 점검용 체크리스트
| 영역 | 점검 항목 | 기준 |
|---|---|---|
| 프록시/게이트웨이 | 타임아웃·버퍼·헤더 크기 | 상류 대비 +10~20% 여유 |
| 애플리케이션 | 스레드/커넥션/큐 한도 | 포화율 70% 이하 유지 |
| 데이터베이스 | 슬로우 쿼리, 락 대기 | P95 500ms 이하 |
| 캐시 | 적중률, 장애 시 폴백 | 적중률 80% 이상 |
| 배포 | 드레인, 롤백 경로 | 원클릭 롤백 가능 |
| 모니터링 | 5xx, 지연, 자원지표 | 알람 임계치 정의 |
12. 고객 영향 최소화를 위한 응답 설계
- 오류 본문에 오류코드, 코릴레이션ID, 문의 경로만 제공하고 내부 정보는 숨긴다.
- 멱등성 키로 재시도 시 중복 처리를 방지한다.
- 정적 유지보수 페이지를 엣지 캐시에 배포한다.
{
"error": "service_unavailable",
"correlationId": "2b8f0a7c-...",
"message": "일시적으로 이용이 불가하다"
}
13. 상황별 실전 시나리오
시나리오 A: 502 급증
- 프록시 에러 로그에서 업스트림별 실패 비율을 확인한다.
- 특정 버전 파드에서만 발생하면 해당 버전을 차단한다.
- TLS 또는 HTTP 버전 불일치가 있으면 동일 프로토콜로 강제한다.
시나리오 B: 503 확산
- 새 배포 직후면 롤백과 드레인 재검을 한다.
- 스레드/커넥션 풀 포화면 한도 상향과 큐 길이 제한을 동시에 적용한다.
- 캐시 미스 폭주 시 TTL·프리워밍을 적용한다.
시나리오 C: 504 주기적 발생
- 외부 API 레이턴시와 성공률을 분리 모니터링한다.
- 서킷브레이커 임계치와 Half-Open 전략을 점검한다.
- 느린 쿼리는 페이징·비동기화로 전환한다.
14. 로그와 추적 설계
- 요청 단위로 TraceID/SpanID를 생성하고 프록시·애플리케이션·DB에 전파한다.
- 에러 로그는 구조화 JSON으로 기록하고 PII는 마스킹한다.
- 샘플링은 정상 1~5%, 오류 100%로 차등 적용한다.
15. 사후 보고서 템플릿
1) 개요: 발생 시각, 영향 범위, 탐지 지표
2) 근본원인: 기술적·조직적 요인 구분
3) 타임라인: 탐지→복구까지의 주요 의사결정
4) 대응평가: 잘한 점/미흡점, 재발방지 액션아이템
5) 지표개선: SLI/SLO, 알람 임계치 조정
FAQ
배포 중 503을 없애려면 무엇을 해야 하나
Readiness Probe 통과 전에는 트래픽을 받지 않도록 하고, 커넥션 드레이닝을 활성화하며, 캐시·DB 마이그레이션은 블루·그린이나 트래픽 미러링으로 검증한다.
502와 504를 빠르게 구분하는 방법은 무엇인가
502는 업스트림 응답이 비정상 또는 즉시 실패하는 패턴이고, 504는 응답 지연으로 타임아웃이 발생하는 패턴이다. 평균 지연시간 상승과 함께라면 504일 가능성이 높다.
클라이언트 재시도는 언제 안전한가
GET·HEAD·멱등 POST에 한해 지수백오프로 2~3회 허용한다. 결제·주문과 같은 비멱등 작업은 멱등키로 보호한다.
상시 모니터링 최소 구성은 무엇인가
5xx율, P95 지연, 요청수, CPU·메모리·FD, DB 연결수, 캐시 적중률, 외부 API 성공률을 대시보드로 통합한다.
에러 페이지에 무엇을 노출해야 하나
오류 코드, 간단 메시지, 코릴레이션ID, 재시도 지침만 노출한다. 스택트레이스나 내부 경로는 노출하지 않는다.