Internal Server Error

개요

500 Internal Server Error는 서버가 요청을 처리하다가 예상치 못한 상황을 만나 실패했음을 알리는 포괄적(catch-all) 오류입니다. 클라이언트 요청 자체는 문제가 없을 수 있으며, 원인은 서버 코드나 그 의존성 쪽에 있습니다.

이 코드는 구체적인 원인을 알려주지 않습니다. 실제 원인(예외, 스택 트레이스, 실패한 쿼리)은 서버 로그에 있으므로, 500을 만나면 가장 먼저 서버 로그와 요청 ID를 확인해야 합니다.

언제 발생하나

• 서버 코드에서 처리되지 않은 예외(unhandled exception)가 발생했을 때
• 데이터베이스·캐시·외부 API 같은 의존성이 실패했을 때
• 환경 변수 누락·잘못된 배포 등 서버 설정 오류가 있을 때

요청 / 응답 예시

GET /api/orders/42 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{"error":"internal_error","requestId":"a1b2c3d4"}

코드로 보기

// Central error middleware: log the detail, return a generic 500
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'internal_error', requestId: req.id });
});

@app.errorhandler(Exception)
def handle(err):
    app.logger.exception(err)
    return jsonify(error='internal_error'), 500

실무 참고

• 보안을 위해 500 응답 본문에 스택 트레이스나 내부 경로를 노출하지 마세요. 대신 요청 ID를 주고 상세는 로그에서 대조하게 합니다.
• 500은 서버 측 오류라 클라이언트가 재시도해도 대개 그대로 실패합니다(멱등 요청은 제한적 재시도 가치 있음).
• 500이 급증하면 방금 배포한 변경, 만료된 시크릿, 다운된 의존성을 우선 의심하세요.

관련 상태코드

관련 헤더

스펙 근거