Exceções e códigos de status HTTP

Nesta página, relacionamos as exceções fornecidas pela biblioteca endpoints e os códigos de status HTTP compatíveis com o Cloud Endpoints Frameworks.

Em muitas situações, convém usar códigos de status HTTP comuns para indicar o sucesso ou a falha da solicitação de API de um usuário. Por exemplo, se um usuário está tentando recuperar uma entidade que não existe, convém enviar um código de status HTTP 404 para dizer que não existe nenhuma entidade com o ID: entityId.

É possível enviar códigos de status HTTP comuns lançando uma exceção fornecida pela biblioteca endpoints da maneira a seguir:

throw new NotFoundException(user.getEmail());

Exceções fornecidas pelo Endpoints Frameworks

O Endpoints Frameworks fornece as seguintes exceções, correspondentes a códigos de status HTTP específicos:

Exceção	Código de status HTTP correspondente
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

Códigos de status HTTP compatíveis

O Cloud Endpoints Frameworks é compatível com um subconjunto de códigos de status HTTP nas respostas da API. A tabela a seguir descreve os códigos compatíveis.

Códigos de status HTTP	Compatibilidade
HTTP 2xx	HTTP 200 é normalmente assumido pelo Endpoints Frameworks se o método da API retornar com sucesso. Se o tipo de resposta do método da API for void ou o valor de retorno do método da API for null, HTTP 204 é definido em vez disso.
HTTP 3xx	Códigos HTTP 3xx não são compatíveis. O uso de qualquer código HTTP 3xx resulta em uma resposta HTTP 404.
HTTP 4xx	Apenas os seguintes códigos HTTP 4xx são compatíveis: 400 401 403 404 409 410 412 413 Quaisquer outros códigos HTTP 4xx são retornados como erro 404, com exceção dos seguintes: 405 é retornado como 501 408 é retornado como 503
HTTP 5xx	Todos os códigos de status HTTP 5xx são convertidos em HTTP 503 na resposta do cliente.

Importante: não use classes de exceção personalizadas para retornar códigos HTTP 2xx. O Endpoints Frameworks não é compatível com o retorno de HTTP 201 ou qualquer outro código 2xx, exceto HTTP 200 e HTTP 204, conforme descrito acima.

Como criar classes de exceção próprias

Se quiser criar outras classes de exceção para outros códigos de status HTTP, será necessário criar uma subclasse com.google.api.server.spi.ServiceException. O snippet a seguir mostra como criar uma classe de exceção que representa um código de status 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);
  }
}

Importante: uma exceção não percebida no aplicativo resulta em um erro HTTP 503 da API do Cloud Endpoints, a menos que ela estenda com.google.api.server.spi.ServiceException.

Como usar códigos de status HTTP não compatíveis

É possível usar códigos de status HTTP que não estejam na lista de compatibilidade acima. Se você decidir fazer isso, poderá haver consequências indesejadas para as bibliotecas de cliente que acessam a API. Para usar códigos de erro não compatíveis, crie sua própria classe de exceção, conforme descrito na seção anterior, e adicione um novo parâmetro de inicialização de servlet enableExceptionCompatibility a 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>