HTTP 상태 코드로 빠르게 원인 찾기
상태 코드는 문제의 “종류”를 빠르게 알려줍니다. 하지만 정확한 원인은 로그와 함께 봐야 합니다. 404 하나만 보고 라우팅 문제라고 단정하면 인증, 프록시, 캐시, 리버스 프록시 설정을 놓칠 수 있습니다. 상태 코드는 출발점이지 최종 결론이 아닙니다.
1) 4xx와 5xx의 차이
- 4xx: 클라이언트 요청 문제 (잘못된 요청, 인증 실패 등)
- 5xx: 서버 처리 문제 (예외 발생, 의존 서비스 장애 등)
2) 자주 쓰는 코드 정리
- 400: 요청 형식 오류
- 401: 인증 필요
- 403: 권한 없음
- 404: 리소스 없음
- 409: 충돌(중복, 상태 불일치)
- 429: 요청 과다
- 500: 서버 내부 오류
- 502/503: 게이트웨이/서비스 장애
3) 디버깅 흐름
- 상태 코드 확인
- 요청 파라미터/헤더/바디 검증
- 서버 로그 확인 (에러 스택, 요청 ID)
- 의존 서비스 상태 점검
- 프록시/CDN/WAF 계층이 응답을 바꿨는지 확인
4) 실무 팁
- 5xx가 반복되면 알림/모니터링을 우선 설정하세요.
- 4xx가 많으면 API 문서/검증 로직을 점검하세요.
- 인증이 섞인 API는 401과 403을 구분해서 기록하세요.
5) 바로 써보기
HTTP Status Lookup에 코드를 넣고 의미를 빠르게 확인하세요.
6) 로그에서 확인해야 할 것
- 요청 ID (트레이싱용)
- 요청 파라미터/바디 요약
- 사용자/인증 정보
- 서버 예외 스택 트레이스
7) 재현을 위한 최소 요청
문제를 재현하려면 가장 작은 요청으로 테스트하세요. 복잡한 요청보다 디버깅 속도가 빠릅니다.
8) 자주 헷갈리는 코드
401은 보통 인증이 없거나 유효하지 않다는 뜻이고, 403은 인증은 되었지만 권한이 부족하다는 뜻입니다. 404는 리소스가 없을 수도 있지만, 보안을 위해 존재 여부를 감추기 위한 응답일 수도 있습니다. 429는 단순 트래픽 증가보다 레이트 리밋 정책, IP 차단, 백오프 미구현과 관련이 많습니다.
9) 운영 환경에서 봐야 하는 계층
애플리케이션 서버가 200을 반환했는데 CDN이 502를 내보내는 경우도 있습니다. 반대로 프록시에서 인증이 막혀 앱 로그에는 요청 자체가 남지 않을 수도 있습니다. 그래서 문제를 볼 때는 브라우저 개발자도구, CDN/WAF 로그, 앱 로그, DB 또는 외부 API 상태까지 계층별로 나누어 보는 습관이 중요합니다.
10) 체크리스트
- 상태 코드가 일관되게 재현되는가?
- 서버 로그에 예외가 남는가?
- 권한/인증 헤더가 올바른가?
- 프록시나 CDN이 응답을 바꾸고 있지 않은가?
11) 문제를 빨리 좁히는 질문
- 이 오류가 특정 사용자에게만 발생하는가
- 특정 리전, 특정 브라우저, 특정 시간대에만 발생하는가
- 최근 배포 이후 시작되었는가
- 재시도하면 성공하는가, 항상 실패하는가
이 질문들만 정리해도 원인 후보가 크게 줄어듭니다.