[Spring Rest API] REST API 설계 규칙 - 2

 

[부록] Google Rest Api에서 쓰는 Error Code

STANDARD SUECCSS

200 (“OK”)

일반적인 요청 성공을 나타내는 데 사용해야 한다.

200은 클라이언트가 요청한 어떤 액션이었뜬지 REST API가 성공적으로 수행했음을 나타내는 코드로, 클라이언트는 이 코드를 받길 원한다. 또한 더 이상의 할당된 ‘2xx’ 계열의 응답코드가 없다는 뜻이기도 하다. 204 상태 코드와는 달리 200코드는 응답 바디가 포함된다.

201(‘Created’)

성공적으로 리소스를 생성했을 때 사용한다.

새로운 리소스를 이용하여 컬렉션에 생성했거나 스토어에 추가했을 때 201 상태 코드로 응답한다. 컨트롤러의 행동으로 새로운 리소스가 생겨났을 경우에도 201 상태 코드로 응답한다. POST 시 거의 대부분 201 코드가 사용된다고 생각하면 된다.

202(“Accepted”)

비동기 처리가 성공적으로 시작되었음을 알릴 때 사용해야 한다.

202 응답은 클라이언트의 요청이 비동기적으로 처리될 것임을 나타낸다. 이 응답상태 코드는 유효한 요청이었지만, 최종적으로 처리되기 까지는 문제가 생길 수도 있다는 것을 클라이언트에게 알려준다. 보툥 202 응답은 처리 시간이 오래 걸리는 액션에 사용된다.

204(“No Content”)

응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다.

204 상태 코드는 보통 PUT, POST, DELETE 요청에 대한 응답으로 이용하는데, REST API가 응답 메시지의 바디에 어떠한 상태 메시지나 표현을 포함해서 보내지 않을 때 사용한다. API는 GET 요청에 204로 응답할 수 있는데, 요청된 리소스는 존재하나 바디에 포함시킬 어떠한 상태 표현도 가지고 있지 않다는 것을 나타낸다.

STANDARD ERROR RESPONSES

오류 응답시에는 응답 바디를 포함한다.

ERROR RESPONSE BODY

에러 시 형태

{ 
"error": { 
    "errors": [  
        {  
            "domain": "global",  
            "reason": "notFound",  
            "message": "Not Found"  
        } 
    ], 
    "code": 404, 
    "message": "Not Found"
 }
}

ERRORS

301 (“Moved Permanently”)

리소스를 이동시켰을 때 사용한다. REST API 리소스 모델이 상당 부분 재설계되었거나 계속 사용할 새로운 URI를 클라이언트가 요청한 리소스에 할당하였다는 것을 나타낸다. REST API는 응답의 Location 헤더에 새로운 URI를 기술해야 한다.

Error Code	Description
movedPermanently	리소스를 이동시켰을 때 사용한다. REST API 리소스 모델이 상당 부분 재설계되었거나 계속 사용할 새로운 URI를 클라이언트가 요청한 리소스에 할당하였다는 것을 나타낸다. REST API는 응답의 Location 헤더에 새로운 URI를 기술해야 한다.

303 (“See Other”)

다른 URI를 참조하라고 알려줄 때 사용한다. 303응답은 처리가 끝난 컨트롤러 리소스가 잠재적으로 원하지 않는 응답 바디를 보내는 대신, 응답 리소스의 URI를 보냈음을 나타낸다. 이것은 임시 상태 메시지의 URI일 수도 있고, 이미 존재하는 영구적인 리소스의 URI일 수도 있다.

303 상태 코드는 일반적으로 REST API가 클라이언트에 상태 다운로드를 강요하지 않으면서 참조 리소스를 보내는 것을 허용한다. 대신 클라이언트는 응답 Location 헤더에 있는 값으로 GET 요청을 보낼 수 있다.

Error Code	Description
seeOther	요청은 성공적으로 처리되었다. 응답을 얻기 위해서는 Location 헤더에 지정된 URL에 GET 요청을 보내라.
mediaDownloadRedirect	요청은 성공적으로 처리되었다. 응답을 얻기 위해서는 Location 헤더에 지정된 URL에 GET 요청을 보내라.

304 (“Not Modified”)

대역폭을 절약할 때 사용한다.

이 상태 코드는 응답 바디에 아무것도 없어야 한다는 측면에서 204 (“No Content”)와 유사하다. 주요 차이점은 204는 바디에 보낼 내용이 없을 때 사용하는 반면, 304는 리소스에 대한 상태 정보가 있긴 하지만 클라이언트에 이미 해당 상태의 최신 버전이 있다는 걸 의미할 때 사용한다.

Error Code	Description
notModified	If-None-Match 헤더에 설정된 조건이 충족 되지 않았다.If-None-Match 의 값과 서버의 값이 달라야 요청에 대한 데이터를 보내준다.304 응답 발생시 클라이언트는 자신의 캐시에 있는 데이터를 그냥 사용하면 된다.

307 (“Temporary Redirect”)

클라이언트가 다른 URI로 요청을 다시 보내게 할 때 사용해야 한다. 307 응답은 REST API 가 클라이언트의 요청을 처리하지 않을 것임을 나타낸다. 클라이언트는 응답 메시지의 Location 헤더에 지정된 URI로 요청을 다시 보내야한다.

Error Code	Description
temporaryRedirect	요청을 Location 헤더에 지정된 URL로 다시 보내라.

400 (“Bad Request”)

일반적인 요청 실패에 사용해야 한다. 기본적으로 다른 4xx 응답들과 매칭되는게 없는 REST API 고유의 에러 정보를 응답 바디에 포함하여 더 자세하게 에러 정보를 표시할 수 있다.

Error Code	Description

401 (“Unauthorized”)

클라이언트 인증에 문제가 있을 때 사용해야 한다.

401 오류 응답은 클라이언트가 적절한 인증 없이 보호된 리소스를 사용하려고 할 때 발생한다. 인증을 잘못하거나 아예 인증하지 못할 경우 발생한다.

Error Code	Description
unauthorized	해당 사용자는 해당 요청에 대한 인증된 사용자가 아니다.
authError	요청에 제공된 인증 자격 증명이 유효하지 않습니다. 인증 HTTP 요청 헤더의 값을 확인하십시오.
expired	세션이 만료되었다. Authorization HTTP 요청 헤더 값을 확인하라.
lockedDomainExpired	이전에 유효한 고정 도메인이 만료 되었기 때문에 요청이 실패했다.
required	사용자는 이 API 요청을 하려면 로그인을 해야한다. 인증 HTTP 요청 헤더 값을 확인해라.

402 (“PAYMENT_REQUIRED”)

요금에 대한 오류 반환이다.

Error Code	Description
dailyLimitExceeded402	일일 사용 요금 한도를 초과했다.
quotaExceeded402	요청한 작업 할당량이 허용하는 것보다 더 많은 자원을 필요로한다. 즉 금액이 모자란다.
user402	요청한 작업은 인증된 사용자의 지불 방식을 필요로한다.

403 (“Forbidden”)

인증 상태에 상관없이 액세스를 금지할 때 사용해야 한다.

403 오류 응답은 클라이언트의 요청은 정상이지만, REST API가 요청에 응하지 않는 경우를 나타낸다. 즉 403 응답은 인증에 문제가 있어서가 아니다. 만약 인증에 문제가 있다면 401를 사용해라. REST API에서 어플리케이션 수준의 접근 권한을 적용하고자 할 때 403을 사용한다. 예를 들어 클라이언트는 REST API 리소스의 전체가 아니라 일부에 대한 접근만 허가된 경우가 있다. 클라이언트가 허용된 범위 외의 리소스에 접근하려고 할 때 REST API는 403으로 응답해야 한다.

Error Code	Description
forbidden	요청이 금지되어 완료되지 못했다.
accessNotConfigured	해당 프로젝트가 이 API 호출에 접근권한이 없다.
accessNotConfigured	해당 프로젝트가 블록당했다.
accountDeleted	요청에 대한 인증 자격 증명과 관련된 사용자 계정이 삭제되었다.
accountDisabled	요청에 대한 인증 자격증명과 관련된 사용자 계정이 사용불가상태이다.
accountUnverified	요청을 하는 사용자의 이메일 혹은 id가 확인 되지 않았다. 혹은 인증이 확인되지 않았다.
concurrentLimitExceeded	동시 사용 한계 때문에 금지 되었다.
dailyLimitExceeded	API의 일일 할당량 제한에 도달했다.
dailyLimitExceeded	일일 할당량 제한에 도달 하고 있으며 이 사용자는 차단되었다.
dailyLimitExceededUnreg	인증되지 않은 API 사용을 위한 일일 한도를 초과했기 때문에 실패했다.
downloadServiceForbidden	이 API는 다운로드를 지원하지 않는다.
insufficientAudience	요청 이 시청자에 대해 완료 될 수 없다.
insufficientAuthorizedParty	요청은 어플리케이션에 대해 완료 할 수 없다.
insufficientPermissions	인증된 사용자이지만 이 요청을 실행 할 수 있는 권한은 없다.
limitExceeded	요청은 액세스 또는 속도 제한으로 인해 완료되지 않을 수 있다.
lockedDomainForbidden	이 API는 락된 도메인을 지원하지 않는다.
quotaExceeded	요청한 작업 할당량이 허용하는 것보다 더 많은 자원을 필요로 한다.
rateLimitExceeded	너무 많은 요청을 주어진 범위내에서 보냈다.
rateLimitExceededUnreg	속도 제한이 초과되었다. API 호출을 계속 할 수 있도록 조치를 취해야한다.
responseTooLarge	요청된 리소스가 반환하기에 너무 크다.
servingLimitExceeded	API 에 지정된 전체 속도 제한은 이미 도달했다.
sslRequired	해당 작업은 SSL을 써야한다.
unknownAuth	API 서버는 요청에 사용되는 인증 방식을 인식하지 못한다. Authorization HTTP 요청헤더를 확인해라.
userRateLimitExceeded	사용자 별 속도 제한에 도달했기 때문에 요청이 실패
userRateLimitExceededUnreg	사용자 별 속도 제한에 도달했고 이 클라이언트는 식별되지 않았다.
variableTermExpiredDailyExceeded	변수가 만료되었고 일일 한계량을 초과했다.
variableTermLimitExceeded	변수의 할당 제한에 도달했기 때문에 요청이 실패했다.

404 (“Not Found”)

요청 URI에 해당하는 리소스가 없을 때 사용한다.

404 오류 상태 코드는 말그대로 클라이언트가 요청한 URI에 해당하는 리소스가 존재하지 않을 때 사용한다.

Error Code	Description
notFound	요청과 관련된 리소스가 존재하지 않는다.
notFound	요청과 관련된 리소스를 찾을 수 없다.
unsupportedProtocol	요청에 사용된 프로토콜은 지원하지 않는다.

405 (“Method Not Allowed”)

HTTP 메서드가 지원되지 않을 때 사용해야 한다.

클라이언트가 허용되지 않는 HTTP 메서드를 사용하려 할 때, API는 405 오류 응답을 한다. 읽기 전용 리소스는 GET 메소드와 HEAD 메서드만 지원하며, 컨트롤러 리소스는 PUT 메서드와 DELETE메서드를 제외한 GET 메서드와 POST 메서드만 허용할 것이다.

405 응답에는 Allow 헤더가 포함되어야 하며, 그 값으로 리소스가 지원하는 HTTP 메서드를 다음 예와 같이 나타내야 한다.

Allow : GET, POST

Error Code	Description
httpMethodNotAllowed	이 리소스에 대한 HTTP 메소드는 지원하지 않는다.

406 (“Not Acceptable”)

요청된 리소스 미디어 타입을 제공하지 못 할 때 사용해야 한다.

406 오류 응답은 클라이언트의 Accept 요청 헤더에 있는 미디어 타입중 해당하는 것을 만들지 못할 때 발생한다. 예를 들어, API가 json(application/json) 데이터 포맷만 지원한다면 xml(application/xml) 포맷 데이터를 요청한 클라이언트는 406 응답을 받는다.

Error Code	Description
notAcceptable	해당 미디어 타입은 제공하지 않는다.

409 (“Conflict”)

리소스 상태에 위반되는 행위를 했을 때 사용해야 한다.

409 오류 응답은 클라이언트 요청에 의해 REST API 리소스가 불가능 또는 모순 상태가 될 수 있는 경우에 사용한다. 예를 들어 클라이언트가 비어 있지 않은 리소스를 삭제하라고 요청하면, REST API에서 이 응답 오류를 보낸다.

Error Code	Description
conflict	요청된 작업이 기존 항목과 충돌하기 때문에 API 요청을 완료 할 수 없다. 중복 항목에 대한 오류는 일반적인 상황보다 좀더 구체적으로 표현한다.
duplicate	이미 존재하는 리소스를 생성하라고 했을 때 발생한다.

410 (“Gone”)

존재 하지 않는 리소스에 대한 삭제 요청 시 사용해야 한다.

Error Code	Description
deleted	삭제 요청한 리소스가 이미 존재 하지 않는다.

412 (“Precondition Failed”)

조건부 연산을 지원할 때 사용한다.

412 오류 응답은 특정한 조건이 만족될 때만 요청이 수행되도록 REST API로 알려준다. 클라이언트가 요청 헤더에 하나 이상의 전제 조건(If-Match , If-None_match 등)을 지정할 경우 발생하며, 이러한 조건이 만족되지 않으면 412응답은 요청을 수행하는 대신에 이 상태 코드를 보낸다.

Error Code	Description
conditionNotMet	요청에 If-Match 나 If-None-Match HTTP 헤더의 조건이 충족되지 않았다.

413 (“Request_entity_too_large”)

413 오류 응답은 요청의 크기가 너무 클 때 사용한다.

Error Code	Description
backendRequestTooLarge	요청이 너무 크다.
batchSizeTooLarge	요청에 너무 많은 요소가 포함되어 있다.
uploadTooLarge	요청에 포함된 데이터의 크기가 너무 커서 요청이 실패했다.

415 (“Unsupported Media Type”)

요청의 페이로드에 있는 미디어 타입이 처리되지 못했을 때 사용해야 한다.

415 오류 응답은 요청 헤더의 Content-Type에 기술한 클라이언트가 제공한 미디어 타입을 처리하지 못할 때 발생한다. 예를 들어 API 가 json(application/json)으로 포맷된 데이터만 처리할 수 있을 때, 클라이언트가 xml(application/xml)로 포맷된 데이터로 요청하면 415응답을 받는다.

Error Code	Description
unsupportedMediaType	요청에 포함된 미디어 타입을 처리하지 못한다.

416 (“Requested Range Not Satisfiable”)

요청이 만족될 수 없는 범위를 지정할 때 사용한다.

Error Code	Description
requestedRangeNotSatisfiable	요청이 만족될 수 없는 범위를 지정할 때 사용한다.

417 (“Expectation Failed”)

클라이언트의 기대가 서버에 의해 만족 될 수 없을 때 사용한다.

Error Code	Description
expectationFailed	클라이언트의 기대가 서버에 의해 만족 될 수 없다.

428 (“Precondition Required”)

해당 요청이 전제 조건이 꼭 필요 할 때 사용한다. 이 요청이 성공하려면 If-Match나 If-None-Match 헤더가 요청에 포함되어야 한다.

Error Code	Description
preconditionRequired	해당 요청이 전제 조건이 꼭 필요 할 때 사용한다. 이 요청이 성공하려면 If-Match나 If-None-Match 헤더가 요청에 포함되어야 한다.

429 (“Too Many Requests”)

너무 많은 요청이 같은 시간에 발생 했을 경우 사용한다.

Error Code	Description
rateLimitExceeded	너무 많은 요청이 주어진 시간 범위 내에서 보냈다.

500 (“Internal Server Error”)

API가 잘못 작동할 때 사용해야 한다.

500 오류 응답은 일반적인 REST API오류 응답이다. 웹 프레임워크는 대부분 예외 사항을 발생시키는 요청 핸들러 코드가 실행 될 경우 자동적으로 이 응답 코드를 발생시킨다. 500 오류는 클라이언트의 잘못으로 발생한 것이 아니기 때문에 클라이언트가 이 응답을 발생시킨 것과 동일한 요청을 다시 시도하면 다른 응답을 받을 수도 있다.

Error Code	Description
internalError	요청이 내부 오류로 인해 실패했다.

501 (“Not Implemented”)

REST API 가 아직 구현되지 않았을 때 이 응답을 사용한다. 설계에서부터 없던 API가 아닌 지원할 것이지만 아직 구현하지 않았을 때 사용한다.

Error Code	Description
notImplemented	해당 요청에 대한 명령은 아직 구현하지 않았다.
unsupportedMethod	요청이 알려지지 않은 메소드나 명령을 실행하려 했기 때문에 실패했다.

503 (“Service Unavailable”)

RESTFUL 서버가 점검중이거나 장애발생시 서비스에 연결 되지 않을 때 사용한다.

Error Code	Description
backendError	백엔드 오류가 발생했다.
backendNotConnected	요청이 연결오류로 실패했다.
notReady	API 서버가 아직 준비되지 않았다.