예외 및 HTTP 상태 코드

이 페이지에서는 endpoints 라이브러리에서 제공되는 예외와 Cloud Endpoints Frameworks에서 지원되는 HTTP 상태 코드를 보여줍니다.

사용자의 API 요청 성공 또는 실패 여부를 나타낼 때는 공통 HTTP 상태 코드를 사용하려는 경우가 많습니다. 예를 들어 사용자가 존재하지 않는 개체를 가져오려고 하면 HTTP 404 상태 코드를 전송하여 ID가 entityId인 개체가 존재하지 않는다고 알릴 수 있습니다.

다음과 같이 endpoints 라이브러리에서 제공되는 예외를 발생시켜서 공통 HTTP 상태 코드를 전송할 수 있습니다.

throw new NotFoundException(user.getEmail());

Endpoints Frameworks에서 제공되는 예외

Endpoints Frameworks는 특정 HTTP 상태 코드에 따라 다음과 같은 예외를 제공합니다.

예외 해당 HTTP 상태 코드
com.google.api.server.spi.response.BadRequestException HTTP 400
com.google.api.server.spi.response.UnauthorizedException HTTP 401
com.google.api.server.spi.response.ForbiddenException HTTP 403
com.google.api.server.spi.response.NotFoundException HTTP 404
com.google.api.server.spi.response.ConflictException HTTP 409
com.google.api.server.spi.response.InternalServerErrorException HTTP 500
com.google.api.server.spi.response.ServiceUnavailableException HTTP 503

지원되는 HTTP 상태 코드

Cloud Endpoints Frameworks에서는 API 응답에서 HTTP 상태 코드 일부가 지원됩니다. 지원되는 코드는 다음 표에 설명되어 있습니다.

HTTP 상태 코드 지원
HTTP 2xx API 메서드가 성공적으로 반환되면 일반적으로 Endpoints Frameworks에서 HTTP 200이 사용됩니다.
API 메서드의 응답 유형이 void이거나, 혹은 API 메서드의 반환 값이 null이면 204가 대신 설정됩니다.
HTTP 3xx HTTP 3xx 코드는 지원되지 않습니다. HTTP 3xx 코드를 사용하면 HTTP 404 응답이 발생합니다.
HTTP 4xx 다음 HTTP 4xx 코드만 지원됩니다.
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
다음을 제외하고 다른 모든 HTTP 4xx 코드는 404 오류로 반환됩니다.
  • 405는 501로 반환됨
  • 408는 503로 반환됨
HTTP 5xx 모든 HTTP 5xx 상태 코드는 클라이언트 응답에서 HTTP 503으로 변환됩니다.

고유한 예외 클래스 만들기

다른 HTTP 상태 코드에 대해 다른 예외 클래스를 만들려면 com.google.api.server.spi.ServiceException을 서브클래스로 만들어야 합니다. 다음 스니펫은 HTTP 408 상태 코드를 나타내는 예외 클래스의 생성 방법을 보여줍니다.

import com.google.api.server.spi.ServiceException;

// Exceptions must inherit from ServiceException
public class RequestTimeoutException extends ServiceException {
  public RequestTimeoutException(String message) {
    super(408, message);
  }
}

지원되지 않는 HTTP 상태 코드 사용

위의 지원 목록에 없는 HTTP 상태 코드도 사용할 수 있습니다. 단, 이 경우 API에 액세스하는 클라이언트 라이브러리에 의도하지 않은 결과가 발생할 수 있습니다. 지원되지 않는 오류 코드를 사용하려면 먼저 이전 섹션에서 설명한 대로 커스텀 예외 클래스를 만든 후 새로운 서블릿 초기화 매개변수인 enableExceptionCompatibility를 EndpointsServlet에 추가합니다.

  <servlet>
    <servlet-name>com.google.api.server.spi.EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
      <param-name>services</param-name>
      <param-value>...</param-value>
    </init-param>
    <init-param>
      <param-name>enableExceptionCompatibility</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>