Server ) RESTful API, 자주 사용하는 Status code 정리 및 예시

개인적으로 공부겸, 메모용으로  작성한 글 입니다 :)

 

2xx Sucess 요청 성공

서버가 클라이언트의 요청을 성공적으로 처리했음

200 OK	처리 성공에 대한 모든 상태 코드를 200으로 처리해도 상관은 없다. 정책 설계 당시에서 세분화 할 것인지, 말것인지 정할 문제임. ex) GET [/api/user/12] → 12번 회원의 정보를 가져오는데 성공함.
201 Created	처리를 정상적으로 성공했고, 새로운 리소스를 생성함. 보통 POST/PUT 요청에 대한 응답으로 사용됨. * http header에 content-location를 명시해, 생성된 리소스 위치를 알려주면 최고! ex) POST [/api/user] → 신규 회원 정보 생성 완료
202 Accepted	클라이언트의 요청은 정상이나, 서버가 아직 요청 처리를 완료하지 못 함. 비동기식 함수(Callback, Polling ... )를 요청했을때 주로 사용함. 처리 시간이 오래걸리기 때문에 일단, 접수했다고 클라이언트에게 알려주는 것. 접수 완료만 알려주고, 결국 처리 결과는 알려주지 않음. 처리 결과를 보내주는 코드를 따로 짜야한다. 즉, 클라이언트가 접수한 요청의 결과를 알 수 있는, 완료 여부를 알 수 있는 방법을 따로 제공해야한다. ex) 배달의 민족 주문 시스템 생각하기. 주문 → 주문 완료 (202) → ... 배달중 ... → 배달 완료 (200)
204 No Content	클라이언트의 요청은 정상이나, 더이상 컨테츠는 제공하지 않음. 삭제 요청 성공시 리턴하는 상태코드로 자주 사용. 200과 차이점이 http에 body가 담기지 않음.  ex) DELETE [ /api/user ] → 성공 → 삭제했기때문에 리턴할 데이터 없음

 

3xx Redirect 리다이렉트

301 Moved Permanently	요청한 리소스 URI가 변경됨

 

4xx Client Error

클라이언트의 요청이 유효하지 않아 서버가 해당 요청을 수행하지 않았음.

400 Bad Request	클라이언트의 요청이 유효하지 않아 서버가 요청을 수행하지 않음. request body, path, query → 유효성 검사, 범위, 필수값 등에 따라  에러 발생 오류 발생시 body에 오류 발생 원인을 밝히는 것이 좋다. ex) POST [ /api/user ] 신규 회원 생성 → id 값을 입력하지 않은채 post 요청함, GET [ /api/user?userIdx=12 ] → 유효하지 않은 query를 보냈을 경우 *개발 정책에 따라 달라질 수 있음
401 Unauthorized 비인증	클라이언트가 인증되지 않았기 때문에 작업을 진행할 수 없음. *인증과 승인을 구분해 생각해야 한다. 특히 403, 409 코드와 연결지어 생각해보자. 인증 → 권한이 있는지 없는지 확인하는 pre 작업 단계 401 권한 → 인증을 해야 이놈이 권한이 있는지 없는지 확인 가능함 403 승인 → 인증받고, 권한을 봐서 있으면 승인이고, 없으면 짤
403 Forbidden 권한이 없음	클라이언트가 권한이 없기 때문에 작업을 진행할 수 없음. 접근 권한이 없다고 이해하면 됨. ex) 관리자 페이지인데 일반 회원이 요청한 경우
404 Not Found 자원이 없음	클라이언트가 요청한 자원이  존재하지 않음. 경로(url), 자원(json, img 등)이 존재하지 않을때 404를 리턴한다. 즉, 없는걸 달라고 했을때 404 에러를 리턴한다. 대부분의 프레임워크에서 없는 URL경로로 요청했을 경우 404를 리턴해준다. 하지만 자원의 경우 서버에서 처리를 해주어야 하는데, 예를 들어 /api/user/:id 경로로 존재하지 않는 id를 넣어 요청했을때, 해당 id는 없는 값이므로 404를 리턴해야한다.
405 Method Not Allowed 허용되지 않은 메소드	클라이언트의 요청이 허용되지 않는 메소드인 경우. ' 이 요청에 이 메소드를 제공하지 않겠다! ' * 메소드 : GET, POST, PUT, PATCH, DELETE 등 ...
409 Conflict 충돌	클라이언트의 요청이 서버의 상태와 충돌이 발생한 경우 여기서 충돌이란 모호한 개념이다. 즉, 개발자가 정의한 정책에 의해 충돌이라면 409를 리턴하면된다. 모호한 개념일수록 에러 원인을 잘 명시해주자. *HATEOS(헤이티오스) 참고
413 Payload Too Large	요청이 서버가 정의한 한계값 보다 클 경우. 연결을 끊고 에러를 리턴하거나 Retry-After헤더 필드로 돌려보낼 수 있음 ex) 용량이 너무큰 파일을 업로드함 → 413 에러 리턴
429 Too Many Requests	클라이언트가 일정시간 동안 너무 많은 요청을 보낸 경우 * HTTP header Retry-Afer 를 명시해 쿨타임을 알려줄 수 있음. ex)  비정상적인 방법으로 자원을 요청하는 경우 응답한다. 특히 Ddos 공격, Brurw-force 공격 등이 이에 해당한다.

 

5xx Server Errors 서버 오류

서버 오류로 인해 요청을 수행할 수 없음.

500 Internal Server Error	클라이언트의 요청은 통과가 되었으나 처리하는 과정중에 오류가 발생  ex) 서버단에서 오타가 있을 경우, DB 연결 오류, 오버플로우 등...
502 Bad Gateway	서버가 게이트웨이나 프록시 서버 역할을 하면서 업스트림 서버로부터 유효하지 않은 응답을 받았음. * 업스트림 서버 : 프록시 서버 계층 구조에서 상위 서버. 프록시를 거치기 이전 서버 ex) nginx나 apache 등 웹 서버 설정에 문제인 경우가 많음
503 Service Unavailable	서버가 요청을 처리할 준비가 되지 않음. 보통 서버가 점검을 위해 다운되거나 오버로드되어 발생한다. 일시적인 상황를 위해 사용되어야 하며, Retry-After HTTP header 는 가능하다면 서비스 복구를 위한 예상 시간을 포함해야 한다.

클라이언트의 요청은 통과가 되었으나 처리하는 과정중에 오류가 발생했을때 5xx 코드를 리턴한다. 5xx 에러는 개발자의 실수, 수치!! 서버 처리 과정에서 오류가 생기지 않도록 유효성  검사를 철저히하고, 4xx 에러를 리턴하는 것이 바람직하다. (*특히 오버플로우 주의)

Nginx, Apache 등 서버 운용에 사용되는 웹서버의 오류가  아닌 이상 클라이언트가 5xx에러를 볼 수 없도록 만들어야 완성도 높은 api이다.

 

 

---

자주 쓰이는 상황

- 회원 리스트를 요청했을때, DB에 저장된 정보가 하나도 없음

200 & response body에 [] 삽입

→ 해당 url이 존재하고, 사용자의 요청에 문제가 있는 것이 아니기때문에 4xx에러라고 할 수 없다. 또한 서버 처리단에서 오류가 발생한 것도 아니기때문에 '성공' 상태코드 200을 리턴하고 body엔 빈 값을 담는다. 

 

- 아이디 찾기를 했는데 결과가 없을때

위 케이스와 마찬가지.

 

- 아이디 중복체크를 했을때, 이미 가입된 계정일 경우

409 & response body에 충돌 내용 담기

→ 아직 신규 데이터를  등록하는 것도 아니라 400이기엔 애매하다. 서버 처리단에서 결과값과 요청값을 비교해 다시 결과를 도출하는 과정이기 때문에 '충돌'로 보는 것이 맞다고 생각했다. 

 

---

 

참고 링크

[okky] api 요청 후 처리를 어떻게 해야할까에 대한 고민이에요.  

[Tistory] REST API 관점에서 바라보는 HTTP 상태 코드(HTTP status code) ***

[blog] Five Clues That Your API isn't RESTful

[MDN] HTTP 상태코드