초보 백엔드 개발자를 위한 HTTP 상태코드

백엔드 개발자가 꼭 알아야 할 HTTP 상태코드 정리 & Spring Boot 적용 예제

🌐 HTTP 상태코드란?

HTTP 상태코드는 클라이언트의 요청에 대한 서버의 응답 결과를 숫자로 나타내는 방식입니다.
총 5가지 범주로 나뉘며, 각 숫자대는 의미가 다릅니다.

• 1xx (Informational): 요청을 받았으며 처리 중
• 2xx (Success): 요청을 성공적으로 처리함
• 3xx (Redirection): 리다이렉션 필요
• 4xx (Client Error): 클라이언트의 잘못된 요청
• 5xx (Server Error): 서버 내부 오류

✅ 자주 쓰는 상태코드 5가지 (설명 + 사용 예시)

상태코드	의미	사용 예시
200 OK	정상 처리	조회, 성공 응답
201 Created	새 리소스 생성 성공	POST 요청 성공
400 Bad Request	잘못된 요청	필수 값 누락
401 Unauthorized	인증 실패	JWT 누락, 만료
404 Not Found	리소스 없음	잘못된 ID 접근
500 Internal Server Error	서버 내부 에러	예외 처리 실패

⚙️ Spring Boot에서 상태코드 설정하는 방법

① ResponseEntity 사용

명시적으로 상태코드를 설정할 수 있어 다양한 응답 제어에 유리합니다.

@GetMapping("/items/{id}")
public ResponseEntity getItem(@PathVariable Long id) {
    Item item = itemService.findById(id);
    return ResponseEntity.status(HttpStatus.OK).body(item);
}

② @ResponseStatus 활용

예외에 직접 상태코드를 붙여 처리 흐름을 단순화할 수 있습니다.

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ItemNotFoundException extends RuntimeException {}

💡 실전 상황별 상태코드 선택 예시

• 조회 성공: 200 OK
• 조회 결과 없음: 204 No Content
• 등록 성공: 201 Created
• 수정 요청 처리 중: 202 Accepted
• 삭제 성공: 200 OK or 204 No Content
• 인증 실패: 401 Unauthorized
• 권한 없음: 403 Forbidden
• 입력 값 오류: 400 Bad Request + 상세 코드

🚫 데이터가 없거나 요청이 잘못됐을 때, 일부러 에러를 발생시키는 이유

단순히 200 OK로 처리하면 클라이언트가 문제를 인식하지 못할 수 있습니다.
따라서 비즈니스 로직 상 오류는 400 번대 상태코드로 명확히 전달하는 것이 좋습니다.

예: DB에서 결과가 없을 때 명시적으로 400 반환

public Item findItemOrThrow(Long id) {
    return itemRepository.findById(id)
        .orElseThrow(() -> new BusinessException("ITEM_NOT_FOUND", ErrorCode.INVALID_REQUEST));
}

에러 클래스:

@ResponseStatus(HttpStatus.BAD_REQUEST)
public class BusinessException extends RuntimeException {
    private final String errorCode;

    public BusinessException(String message, String errorCode) {
        super(message);
        this.errorCode = errorCode;
    }
}

클라이언트는 다음과 같이 응답을 받을 수 있습니다:

{
  "message": "ITEM_NOT_FOUND",
  "code": "INVALID_REQUEST"
}

🧩 마무리: 응답을 설계하는 백엔드 개발자의 자세

HTTP 상태코드는 단순한 숫자가 아니라 API의 커뮤니케이션 약속입니다.
상태코드를 통해 클라이언트는 결과를 해석하고 적절한 처리를 할 수 있습니다.

✔️ 상태코드 설계 시 체크리스트:

• 모든 요청에 무조건 200 OK를 주고 있지 않은가?
• 비즈니스 실패 상황을 구분하고 있는가?
• 에러 응답의 구조가 일관되어 있는가?

정확한 상태코드와 구조화된 응답은 백엔드 개발자의 품격입니다.