REST API HTTP 상태 코드 제대로 사용하는 방법

REST API HTTP 상태 코드를 올바르게 사용하는 방법을 정리해 드립니다. 200, 201, 204, 400, 401, 403, 404, 409, 422, 500 등 실무에서 자주 사용하는 HTTP Status Code의 의미와 사용 기준, Spring Boot 적용 방법, 잘못된 사용 사례까지 쉽게 이해하실 수 있습니다.

REST API HTTP 상태 코드

REST API를 개발하면서 가장 많이 고민하는 부분 중 하나가 HTTP 상태 코드를 어떻게 반환해야 하는지입니다.

동작은 정상인데 항상 200만 반환하거나, 오류인데도 500을 사용하는 사례는 생각보다 자주 볼 수 있습니다. 하지만 HTTP 상태 코드는 단순한 숫자가 아니라 클라이언트와 서버가 서로의 처리 결과를 명확하게 이해하기 위한 약속입니다.

이번 글에서는 REST API HTTP 상태 코드 제대로 사용하는 방법을 중심으로 실무에서 가장 많이 사용하는 상태 코드와 상황별 사용 기준을 정리해 드리겠습니다.

01. HTTP 상태 코드가 중요한 이유

HTTP 상태 코드를 올바르게 사용하는 기준을 먼저 이해해 보겠습니다.

HTTP 상태 코드는 서버가 요청을 어떻게 처리했는지를 숫자로 알려주는 표준입니다.

예를 들어 API를 호출했을 때

• 요청이 정상인지
• 데이터가 생성되었는지
• 입력값이 잘못되었는지
• 권한이 없는지
• 서버에서 오류가 발생했는지

등을 한 번에 알 수 있습니다.

만약 모든 결과를 200 OK로만 반환한다면 클라이언트는 응답 본문을 직접 분석해야 하므로 개발과 유지보수가 어려워질 수 있습니다.

02. HTTP 상태 코드 분류

가장 먼저 HTTP 상태 코드의 큰 범주를 이해하는 것이 좋습니다.

구분의미대표 코드

1xx	정보 제공	100
2xx	요청 성공	200, 201, 204
3xx	리다이렉션	301, 302
4xx	클라이언트 요청 오류	400, 401, 403, 404, 409, 422
5xx	서버 오류	500, 502, 503

REST API에서는 대부분 2xx, 4xx, 5xx를 사용하게 됩니다.

03. 성공 응답에서 사용하는 상태 코드

성공 응답에서 언제 어떤 상태 코드를 사용하는지 알아보겠습니다.

✓ 200 OK

가장 많이 사용하는 상태 코드입니다.

다음과 같은 경우에 적합합니다.

• 조회 성공
• 수정 성공
• 삭제 성공(응답 데이터가 있는 경우)
• 로그인 성공

예시

• 회원 조회
• 게시글 목록 조회
• 주문 정보 조회

✓ 201 Created

새로운 리소스를 생성했을 때 사용합니다.

예를 들어

• 회원가입
• 게시글 작성
• 상품 등록

과 같이 새로운 데이터가 생성되었다면 201이 적절합니다.

✓ 204 No Content

처리는 성공했지만 반환할 데이터가 없는 경우입니다.

예를 들어

• 삭제 완료
• 수정 완료
• 로그아웃 완료

등에서 많이 사용합니다.

응답 Body는 포함하지 않는 것이 일반적입니다.

04. 클라이언트 오류 상태 코드

사용자가 잘못 요청했을 때 사용하는 상태 코드입니다.

✓ 400 Bad Request

요청 자체가 잘못된 경우입니다.

대표 사례는 다음과 같습니다.

• 필수 값 누락
• JSON 형식 오류
• 잘못된 파라미터

예시

• age가 숫자가 아님
• 이메일 형식 오류

✓ 401 Unauthorized

인증이 필요한데 인증되지 않은 경우입니다.

대표 사례입니다.

• JWT 없음
• Access Token 만료
• 로그인하지 않음

권한 문제가 아니라 인증 실패라는 점이 중요합니다.

✓ 403 Forbidden

인증은 되었지만 권한이 없는 경우입니다.

예를 들어

• 일반 회원이 관리자 API 호출
• 접근 권한 부족

이럴 때는 401이 아니라 403을 사용하는 것이 적절합니다.

✓ 404 Not Found

요청한 리소스를 찾을 수 없는 경우입니다.

대표 사례입니다.

• 존재하지 않는 회원
• 삭제된 게시글
• 없는 주문번호

✓ 409 Conflict

현재 데이터와 충돌하는 경우입니다.

예를 들어

• 이미 존재하는 아이디
• 중복 이메일
• 버전 충돌

등에서 사용할 수 있습니다.

✓ 422 Unprocessable Content

요청 형식은 맞지만 비즈니스 규칙을 만족하지 못하는 경우에 사용할 수 있습니다.

예를 들면 다음과 같습니다.

• 재고 부족
• 주문 가능 수량 초과
• 예약 불가능한 날짜

프로젝트 정책에 따라 400과 함께 사용하는 경우도 있지만, 비즈니스 검증 실패를 구분하고 싶다면 422를 고려할 수 있습니다.

05. 서버 오류 상태 코드

서버 내부에서 예상하지 못한 문제가 발생한 경우입니다.

✓ 500 Internal Server Error

가장 대표적인 서버 오류입니다.

예를 들어

• NullPointerException
• 데이터베이스 오류
• 서버 내부 예외

등이 발생하면 500을 반환할 수 있습니다.

단순 입력 오류를 500으로 반환하는 것은 적절하지 않습니다.

✓ 502 Bad Gateway

프록시 또는 게이트웨이가 다른 서버로부터 올바른 응답을 받지 못한 경우입니다.

API Gateway 환경에서 주로 볼 수 있습니다.

✓ 503 Service Unavailable

서비스를 일시적으로 제공할 수 없는 경우입니다.

예를 들면

• 서버 점검
• 트래픽 과부하
• 유지보수

등에서 사용할 수 있습니다.

06. 실무에서 많이 사용하는 상태 코드 정리

아래 표 정도는 기억해 두시면 대부분의 REST API 개발에서 활용하실 수 있습니다.

상황권장 상태 코드

조회 성공	200 OK
생성 성공	201 Created
삭제 성공	204 No Content
잘못된 요청	400 Bad Request
인증 실패	401 Unauthorized
권한 없음	403 Forbidden
데이터 없음	404 Not Found
중복 데이터	409 Conflict
비즈니스 검증 실패	422 Unprocessable Content
서버 오류	500 Internal Server Error

07. Spring Boot에서는 어떻게 사용하는 것이 좋을까요?

Spring Boot에서는 대부분 ResponseEntity를 활용하여 상태 코드를 반환합니다.

예를 들어

• 조회 성공 → 200
• 등록 성공 → 201
• 삭제 성공 → 204
• Validation 실패 → 400
• 인증 실패 → 401
• 권한 부족 → 403
• 데이터 없음 → 404
• 예외 발생 → 500

처럼 상황에 맞는 상태 코드를 반환하는 것이 좋습니다.

또한 Global Exception Handler(@RestControllerAdvice)를 함께 사용하면 예외를 일관성 있게 처리할 수 있어 유지보수성이 높아집니다.

08. 실무에서 자주 하는 실수

다음과 같은 구현은 가능한 한 피하는 것이 좋습니다.

✓ 모든 응답을 200으로 반환

오류까지 모두 200으로 반환하면 클라이언트가 성공과 실패를 구분하기 어려워집니다.

✓ 모든 오류를 500으로 반환

사용자의 입력 오류까지 500으로 처리하면 실제 서버 장애와 구분하기 어렵습니다.

✓ 인증과 권한을 구분하지 않음

401과 403은 의미가 다르므로 상황에 맞게 사용하는 것이 좋습니다.

✓ 생성 API에서도 200 사용

새로운 리소스가 생성되었다면 201을 사용하는 것이 REST API 설계 원칙에 더 적합합니다.

09. REST API 상태 코드 사용 원칙

실무에서는 아래 기준만 기억해도 대부분의 상황을 올바르게 처리하실 수 있습니다.

• 조회 성공은 200
• 생성은 201
• 삭제는 204
• 입력 오류는 400
• 인증 실패는 401
• 권한 부족은 403
• 데이터 없음은 404
• 중복 충돌은 409
• 비즈니스 검증 실패는 422
• 서버 오류는 500

이 기준을 일관성 있게 적용하면 API를 사용하는 개발자도 훨씬 이해하기 쉬운 서비스를 만들 수 있습니다.

FAQ

Q1. 모든 API를 200 OK로 반환하면 안 되나요?

권장되지 않습니다. HTTP 상태 코드는 요청 처리 결과를 표준화된 방식으로 전달하기 위한 정보이므로 성공과 오류를 적절한 상태 코드로 구분하는 것이 좋습니다.

Q2. 401과 403은 무엇이 다른가요?

401은 인증이 되지 않은 상태를 의미하며, 403은 인증은 되었지만 해당 리소스에 접근할 권한이 없는 상태를 의미합니다.

Q3. 생성 API는 왜 201을 사용하는 것이 좋나요?

새로운 리소스가 생성되었음을 명확하게 표현하기 위해서입니다. REST API에서는 생성 성공 시 201 Created를 사용하는 것이 일반적인 설계 방식입니다.

Q4. 삭제 API는 200과 204 중 무엇을 사용해야 하나요?

삭제 후 응답 데이터를 반환한다면 200을 사용할 수 있으며, 반환할 내용이 없다면 204 No Content를 사용하는 경우가 많습니다.

Q5. Validation 실패는 400과 422 중 어떤 것을 사용해야 하나요?

입력 형식 자체가 잘못된 경우에는 400을 사용하는 경우가 일반적입니다. 형식은 올바르지만 비즈니스 규칙을 만족하지 못하는 경우에는 프로젝트 정책에 따라 422를 사용할 수도 있습니다.

관련글

• JSON 응답 구조 표준화하는 방법과 API 설계 팁
• REST API 응답 형식 ResponseEntity 사용법 총정리