Exceções e códigos de estado HTTP

Esta página apresenta uma lista das exceções fornecidas pela biblioteca endpoints, bem como os códigos de estado HTTP suportados pelos frameworks do Cloud Endpoints.

Em muitas situações, pode querer usar códigos de estado HTTP comuns para indicar o êxito ou a falha de um pedido de API de um utilizador. Por exemplo, se um utilizador estiver a tentar obter uma entidade que não existe, é recomendável enviar um código de estado HTTP 404 para indicar que não existe nenhuma entidade com o ID: entityId.

Pode enviar códigos de estado HTTP comuns ao gerar uma exceção fornecida pela biblioteca endpoints da seguinte forma:

throw new NotFoundException(user.getEmail());

Exceções fornecidas pelos frameworks de pontos finais

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

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

Os frameworks do Cloud Endpoints suportam um subconjunto de códigos de estado HTTP nas respostas da API. A tabela seguinte descreve os códigos suportados.

Códigos de estado HTTP	Apoio técnico
HTTP 2xx	Normalmente, o HTTP 200 é assumido pelos Endpoints Frameworks se o método da API for devolvido com êxito. Se o tipo de resposta do método da API for void ou o valor de retorno do método da API for null, é definido o HTTP 204.
HTTP 3xx	Os códigos HTTP 3xx não são suportados. A utilização de códigos HTTP 3xx resulta numa resposta HTTP 404.
HTTP 4xx	Apenas são suportados os seguintes códigos HTTP 4xx: 400 401 403 404 409 410 412 413 Quaisquer outros códigos HTTP 4xx são devolvidos como erro 404, exceto os seguintes: 405 é devolvido como 501 408 é devolvido como 503
HTTP 5xx	Todos os códigos de estado HTTP 5xx são convertidos em HTTP 503 na resposta do cliente.

Importante: não use classes de exceções personalizadas para devolver códigos HTTP 2xx. O Endpoints Frameworks não suporta a devolução de HTTP 201 nem de quaisquer outros códigos 2xx, exceto HTTP 200 e HTTP 204, conforme descrito na tabela anterior.

Criar as suas próprias classes de exceções

Se quiser criar outras classes de exceções para outros códigos de estado HTTP, tem de criar uma subclasse de com.google.api.server.spi.ServiceException. O fragmento seguinte mostra como criar uma classe de exceção que representa um código de estado 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 capturada na sua aplicação resulta num erro HTTP 503 da sua API Cloud Endpoints, a menos que se estenda com.google.api.server.spi.ServiceException.

Usar códigos de estado HTTP não suportados

É possível usar códigos de estado HTTP que não estejam na lista de códigos suportados acima. Tenha em atenção que, se decidir fazê-lo, pode ter consequências não intencionais para as bibliotecas cliente que acedem à API. Para usar códigos de erro não suportados, crie a sua própria classe de exceção, conforme descrito na secção anterior, e adicione um novo parâmetro de inicialização do servlet enableExceptionCompatibility para 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>