개발
HTTP 500번대 에러 정리 및 해결 방안
목차
지난 글에 이어서 이번에는 서버단에서 발생하는 문제에 대한 에러코드에 대해 알아보고자 한다.
사실 400번대 에러는 클라이언트의 잘못된 요청이 대부분이므로 적당히 에러코드와 함께 메시지를 보여줘 UX를 충족시키면되지만, 500번대는 실제로 서버에서 백단작업중에 의도치 않게 발생하는 문제이므로 유저가 보는 경우가 발생하면 그건 시스템의 신뢰성을 떨어트리는 일이기도하다.
그러므로 빠른 문제파악이 되도록 500번대 에러가 발생하면 해당 에러에 대한 디버깅이 빠르게 하기위한 정보를 가지고 보여줘야하며, 에러코드에 따라서 개발자가 빠르게 상황을 파악해 보완조치를 해야하므로 400번대 에러보다 더 잘 인지하고 있어야하는 부분이기도하다.
| 에러 코드 | 에러 메시지 | 의미 |
|---|---|---|
| 500 | Internal Server Error | 서버 내부에서 오류가 발생했을 때, 일반적인 예외 처리 실패의 경우 |
| 501 | Not Implemented | 서버가 해당 요청 메서드를 구현하지 않았을 때 |
| 502 | Bad Gateway | 게이트웨이나 프록시 서버가 잘못된 응답을 받았을 때 |
| 503 | Service Unavailable | 서버가 일시적으로 과부하/점검 상태로 요청 처리가 불가할 때 |
| 504 | Gateway timeout | 게이트웨이/프록시가 상위 서버로부터 응답을 받지 못할 때 |
이제 하나씩 서버 에러 코드에 대해 알아보자.
500 Internal Server Error
클라이언트의 요청은 올바르지만, 서버 내부에서 예기치 못한 오류가 발생해 요청을 처리하지 못했을때 반환하는 상태 코드이다.
웹 개발을 할때 가장 많이 보는 오류이며, 모든 오류의 디폴트라 볼 수 있다.
이 오류는 어느 상황에 발생하는지 알아보면,
- try-catch로 감싸지 않은 예외(Exception) 발생
- DB 연결 실패, 쿼리 오류 (ex. SQL 구문 오류)
- 파일 접근 실패 (권한, 경로 문제)
- 의존성 서비스(API, Redis 등) 호출 실패
- PHP/JS 코드 상 문법 오류 또는 undefined 변수 접근
- Laravel에서 abort(500)을 명시적으로 호출한 경우
대략 이런 경우때 발생하는 오류이다.
실제 라라벨에서의 발생 예시를 보자면,
$user = User::findOrFail($id); // $id가 null인 경우 내부적으로 500 오류 가능
// 또는
$post->undefinedMethod(); // 존재하지 않는 메소드 호출Copy이런식으로 흔히 로직에서 발생하는 대부분의 오류인 경우 이 500에러를 서버에서 뱉는다고 보면된다.
이런 에러에서는 문제해결하기위해 아래와 같은 접근 방식을 취해볼 수 있다.
1) 로그 확인: storage/logs/laravel.log 등, 로그파일을 통해 가장 먼저 발생한 Exception을 확인
2) 최근 코드 변경: 컨트롤러, 뷰, 서비스 파일에서 최근에 수정된 부분을 우선 점검
3) 외부 시스템: DB, Redis, API 서버 등의 응답 상태 확인 (다운, timeout 등)
4) 배포 문제: .env, 권한 문제, 캐시 미적용 등 배포 환경의 이슈 점검
5) 예외 핸들링 여부: try-catch 또는 Handler에서 제대로 예외 처리가 되는지 확인
실제 실무에서는 개발 단계에서 위 에러가 발생하지않게 디버깅 정보를 상세하게 코드나 로그에 나열하는것이 좋고, 운영단계에서는 이런 에러 원인이 사용자에게는 노출되어서는 안된다.
물론 제일 베스트는 에러가 발생하지않는것이지만, 에러발생시 관련 코드가 사용자에게 노출되는것 자체가 코드를 잘 모르는 사용자에게 해킹이 되고있다는 인식까지 심어줄정도로 신뢰도가 낮아질 수 있기 때문에, 해당 에러 발생시 앞단에 보여지는 페이지는 그럴듯 하게 정보를 보여주면서 백단에서 빠른 로그 확인 후 문제 해결에 착수해야하는 게 좋다.
501 Not Implemented
클라이언트의 요청은 서버로 전달되었지만, 서버가 해당 요청 메서드나 기능을 지원하지 않거나 아직 구현되어 있지 않을 때 반환하는 상태 코드이다.
이 오류는 보통 API 명세에는 있지만 실제로 구현되지 않은 기능을 호출했거나, 서버가 특정 메서드(PUT, PATCH 등)를 처리할 준비가 안 된 경우에 발생한다.
이 오류는 어느 상황에 발생하는지 알아보면,
- API 라우트는 등록되었지만 실제 컨트롤러 메소드가 구현되지 않은 경우
- 서버가 PATCH, PUT, DELETE 등의 HTTP 메서드를 지원하지 않을 때
- nginx, apache 등의 서버 설정에서 특정 메서드를 차단하고 있는 경우
- 외부 API나 프록시 서버가 요청 메서드를 인식하지 못하거나 거부하는 경우
대략 이런 경우 때 발생하는 오류이다.
실제 라라벨에서의 발생 예시를 보자면,
// routes/web.php
Route::post('/api/report', 'ReportController@generate');
// 하지만 ReportController 내부에 generate() 메소드가 없음Copy이런 식으로 존재하지 않는 메소드를 연결하거나, 메서드가 누락된 상태에서 라우트를 호출할 경우 서버는 처리할 수 없다는 의미로 501 에러를 반환하게 된다.
이런 에러에서는 문제해결하기 위해 아래와 같은 접근 방식을 취해볼 수 있다.
1) 요청 메서드 확인: GET, POST 등 올바른 메서드를 사용하고 있는지 확인
2) 라우트 등록 여부 점검: 해당 HTTP 메서드에 대한 라우트가 정확히 등록되어 있는지
3) 핸들러 구현 여부: 라우트와 연결된 컨트롤러와 메소드가 실제로 존재하는지
4) 서버 설정 확인: nginx, apache 등의 웹 서버에서 해당 메서드가 차단되어 있지 않은지
5) 외부 시스템 제한: 사용하는 API나 프록시 서버가 해당 메서드를 지원하는지 여부 확인
실제 실무에서는 이런 오류가 발생할 경우 개발 중 누락된 기능을 호출하고 있을 가능성이 높기 때문에, 우선적으로 “기능이 실제 구현되어 있는지”부터 확인하는 것이 가장 빠른 진단 루트이다.
또한 배포 전 테스트 과정에서 QA나 프론트엔드 팀과의 API 통신에서 자주 발생하므로, API 명세와 실제 구현이 정확히 일치하는지를 항상 확인해두는 것이 좋다.
운영 환경에서는 이 에러가 사용자에게 직접 노출되지 않도록 하고, 프론트엔드에서는 해당 에러가 발생할 경우 적절한 안내 메시지를 보여주는 등 사용자 경험을 방해하지 않도록 처리해주는 것이 중요하다.
특히 외부에서 접근 가능한 API가 501을 응답할 경우에는 문서화된 기능이 오작동하거나 누락되었음을 의미하므로 개발자가 즉시 수정하거나 대응해야 한다.
502 Bad Gateway
502 Bad Gateway는 서버가 게이트웨이 또는 프록시 역할을 할 때, 상위 서버로부터 잘못된 응답을 수신했을 때 반환하는 상태 코드이다.
즉, 요청을 직접 처리하는 서버는 아니고 중간에 위치한 프록시(예: Nginx, AWS ALB, Cloudflare 등)가 뒤쪽 서버로 요청을 보냈는데, 해당 서버가 제대로 응답하지 못했을 경우 발생한다.
이 오류는 어느 상황에 발생하는지 알아보면,
- 프론트 서버(Nginx, ALB 등)에서 연결하려는 백엔드 서버가 죽어있는 경우
- 백엔드 서버가 너무 느려서 프론트에서 timeout으로 끊어버린 경우
- API 요청 중 외부 서비스가 잘못된 응답(빈 응답, 오류 응답 등)을 반환한 경우
- DNS 오류나 포트 충돌로 인해 백엔드 서버와 정상 통신이 되지 않는 경우
- 잘못된 업스트림 설정으로 존재하지 않는 서버 주소를 참조하고 있는 경우
대략 이런 경우 때 발생하는 오류이다.
실제 Nginx에서의 발생 예시를 보자면,
location /api {
proxy_pass http://localhost:8000;
}Copy위 설정 상태에서 localhost:8000의 백엔드 서버가 실행되고 있지 않다면, Nginx는 해당 요청에 대해 502 Bad Gateway를 반환하게 된다.
이런 에러에서는 문제해결하기 위해 아래와 같은 접근 방식을 취해볼 수 있다.
1) 백엔드 프로세스 확인: 요청을 전달받는 서버가 실제로 실행 중인지 확인
2) 포트/주소 설정 점검: Nginx 또는 프록시 설정에서 잘못된 포트나 주소를 사용하고 있지 않은지 확인
3) 백엔드 응답 상태 점검: 서버가 에러 응답이나 빈 응답을 반환하고 있는지 확인
4) 서버 간 연결 테스트: curl, telnet 등을 사용하여 내부 통신이 정상인지 확인
5) 프록시 타임아웃 설정: 프록시가 너무 짧은 시간 내에 타임아웃을 발생시키고 있지는 않은지 설정 확인
실제 실무에서는 여러 서버가 연동되는 구조에서 발생하는 경우가 많기 때문에, 백엔드 서버 자체의 상태보다 앞단 프록시 설정이나 서버 간 네트워크 통신 문제를 먼저 확인하는 것이 빠르다.
Docker, Load Balancer, 클라우드 환경 등에서 자주 발생하는 오류이기도 하며, 에러 발생 위치가 사용자 코드가 아니라 인프라 레벨일 가능성이 높다.
503 Service Unavailable
503 Service Unavailable은 서버가 일시적으로 요청을 처리할 수 없는 상태일 때 반환하는 상태 코드이다.
보통 서버가 과부하 상태이거나 유지보수 중이라 정상적인 요청 처리가 불가능할 때 사용된다.
이는 의도적으로 서비스를 중단했을 수도 있고, 일시적으로 자원이 부족해서 처리하지 못하는 상황일 수도 있다.
이 오류는 어느 상황에 발생하는지 알아보면,
- 서버가 너무 많은 요청을 받아 과부하로 응답 불가 상태인 경우
- 백엔드 서비스(DB, 캐시 등)의 연결이 끊겨 처리가 불가능한 경우
- 서버가 점검/배포 중으로 일시적으로 요청을 차단하도록 설정한 경우
- 큐나 작업 처리가 지연되어 내부 자원 고갈이 발생한 경우
- 컨테이너, 인스턴스 등 서버 자체가 Health Check 실패로 제외된 경우
대략 이런 경우 때 발생하는 오류이다.
예를 들어 Laravel이나 Nginx 환경에서 점검 페이지를 보여주기 위해 명시적으로 이 상태 코드를 반환할 수도 있다.
Laravel에서의 예시를 보자면,
abort(503, '서비스 점검 중입니다');CopyNginx에서는 아래와 같은 방식으로 유지보수 페이지를 설정해 사용할 수 있다.
location / {
if (-f /var/www/html/maintenance.html) {
return 503;
}
}Copy이런 에러에서는 문제해결하기 위해 아래와 같은 접근 방식을 취해볼 수 있다.
1) 서버 상태 확인: CPU, 메모리 사용량, 연결 수 등을 확인하여 과부하 여부 점검
2) 의존 서비스 확인: DB, Redis, 외부 API 등이 모두 정상 동작 중인지 확인
3) 배포 및 점검 여부 확인: 실제 유지보수 중이라면 점검 페이지 설정이 정상인지 확인
4) 서버 재기동 또는 스케일링 고려: 일시적인 부하 해소를 위해 수평 확장이나 재시작
5) 장애 탐지 시스템 확인: 알림 시스템, 헬스체크 로직에서 감지된 문제인지 파악
실제 실무에서는 사용자가 가장 불안해할 수 있는 에러 중 하나로, 의도적 중단인지, 장애 상황인지 명확하게 구분하는 대응이 필요하다.
클라우드나 컨테이너 기반 환경에서는 Auto-Scaling이나 Load Balancer의 헬스체크 실패로 인한 503도 빈번히 발생할 수 있기 때문에, 인프라 레벨에서도 로그 추적이 필수적이다.
서비스 중단을 최소화하기 위해 사전 알림 시스템, 자동 점검 페이지 전환, Graceful Shutdown 등도 함께 고려해야 한다.
504 Gateway Timeout
504 Gateway Timeout은 게이트웨이 또는 프록시 서버가 지정된 시간 내에 상위 서버로부터 응답을 받지 못했을 때 반환하는 상태 코드이다.
즉, 프론트엔드 서버(Nginx, AWS Load Balancer 등)가 백엔드 서버(API 서버 등)로 요청을 보냈지만, 응답이 너무 느려서 중간 서버가 타임아웃으로 종료시켰다는 뜻이다.
이 오류는 어느 상황에 발생하는지 알아보면,
- 백엔드 서버의 처리 시간이 너무 길어 프론트 서버의 타임아웃 한계를 초과한 경우
- 백엔드 서버가 일시적으로 느려지거나 무한 루프에 빠져 응답을 반환하지 못한 경우
- 프록시 서버와 백엔드 서버 간 네트워크 연결이 불안정한 경우
- 프론트 서버(Nginx 등)의 timeout 설정 값이 너무 짧게 설정된 경우
- AWS ALB, Cloudflare 등의 중간 서비스가 응답을 받지 못하고 자체 종료한 경우
대략 이런 경우 때 발생하는 오류이다.
예를 들어 Laravel API 서버가 복잡한 연산이나 외부 API 호출을 처리하느라 30초 이상 걸리는 상황에서,
Nginx가
proxy_read_timeout 10;처럼 짧게 설정되어 있다면 요청은 끊기고 504 Gateway Timeout이 발생할 수 있다.이런 에러에서는 문제해결하기 위해 아래와 같은 접근 방식을 취해볼 수 있다.
1) 백엔드 처리 시간 측정: 실제로 API나 작업 로직이 비정상적으로 오래 걸리는지 확인
2) 프록시 타임아웃 설정 확인: Nginx, ALB 등의 read/connect timeout 값을 확인 및 조정
3) 백엔드 서버 상태 점검: DB 쿼리 지연, 무한루프, 대기열 과부하 등 확인
4) 로그 기반 원인 추적: Laravel 로그, 웹 서버 로그 등을 통해 지연 원인을 분석
5) 비동기 처리 고려: 처리 시간이 오래 걸리는 작업은 큐나 백그라운드로 분리
실제 실무에서는 백엔드에서 정상적으로 로직이 완료되었더라도, 응답이 너무 늦어 프론트가 먼저 연결을 끊어버리는 경우가 많다. (보통 이런 타임아웃은 60초로 되어있다)
이 경우 사용자 입장에서는 “서버가 멈췄다”고 느낄 수 있으므로, 시간이 오래 걸리는 작업은 사용자 피드백을 제공하거나, 응답을 미루지 않도록 설계하는 것이 중요하다.
또한 클라우드 기반 인프라에서는 Load Balancer의 timeout 설정이나, 외부 API 응답 지연이 주요 원인이 될 수 있으니 네트워크 및 외부 연동 부분도 함께 체크해야 한다.
여기까지 가장 빈번하게 볼만한 500번대 서버 에러에 대해 알아보았다.
각자 구현한 웹서버와 서비스에 따라 에러 사항은 다 다르겠지만 큰 틀에서 이런류의 문제가 발생하고있다고 보면 될것같다.
사용자가 뭘 할 수있는 에러가 아니라 개발자나 시스템 관리자 선에서의 에러라 인지하면 되는 느낌이다.
400번대 클라이언트 에러 관련 정리글 보러가기:
#Protocol #Laravel
0
개의 댓글
개발 카테고리의 다른 글
05/08
HTTP 400번대 에러 정리 및 추천 메시지
최근에 백단 컨트롤러에서 잘못된 요청에 따른 예외처리를 할일이 있어서 400번대 에러코드에 대해 알아보다가 한번 정리가 필요할듯 싶어서 관련내용을 조사해보고 정리해보았다. 일반적으로 HTTP 400번대 에러는 '클라이언트의 잘못된 요청'으로 인해 서버가 정상적인 응답을 할 수 없을때 나타내는 에러코드이다.유명한...
04/30
brew로 설치한 mysql 8버전 실행 문제 (해결실패...)
가끔 로컬에서 디비작업할 일이 있어서 로컬에 mysql을 깔아두고 필요할때만 쓰고있었다.근데 최근에 다시 쓸일이 있어 mysql을 작동하려는데 아래와 같은 메시지가 뜨며 제대로 실행되지 않았다. 뭔소린가 싶어서 지피티한테 물어봤더니 모종의 brew 작업중 plist가 깨지거나 mysql 자체의 오류가 있어서 발생하는 문제라...
04/30
ChatGPT 협업 기능으로 PHPStorm 코드 작업하기
이야, 요즘 개발작업하는데 지피티를 안쓰는 경우는 거의없지만 이제 여기까지 될줄은 정말 몰랐다. 무슨이야기인가 하면 이제 앱으로 실행시키는 채찍피티(ChatGPT ㅋㅋㅋ)로 내 IDE인 피스톰(PHPStorm)에 직접 접근시켜 코드를 물어보고 수정할 수 있다는 말이다. 엥 이거완전 헛소리아니냐? 싶겠다만 되는걸 어찌하라고...
