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.

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);
  }
}

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>