Exceções e códigos de status HTTP

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, você pode querer enviar um código de status HTTP 404 para dizer que nenhuma entidade com o ID entity_id existe.

Importante: uma exceção não capturada no seu aplicativo resulta em um erro HTTP 503 da sua API backend.

É possível enviar esses códigos de status HTTP comuns gerando uma exceção fornecida pela biblioteca do Endpoints desta maneira:

message = 'No entity with the id "%s" exists.' % entity_id
raise endpoints.NotFoundException(message)

Exceções fornecidas pelo Endpoints Frameworks

A biblioteca do Endpoints fornece as exceções a seguir, correspondentes a códigos de status HTTP específicos:

Exceção	Código de status HTTP correspondente
endpoints.BadRequestException	HTTP 400
endpoints.UnauthorizedException	HTTP 401
endpoints.ForbiddenException	HTTP 403
endpoints.NotFoundException	HTTP 404
endpoints.InternalServerErrorException	HTTP 500

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 VoidMessage ou o valor de retorno do método da API for None, 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 você quiser criar outras classes de exceção para outros códigos de status HTTP, poderá fazer isso com a subclasse endpoints.ServiceException. O snippet a seguir mostra como criar uma classe de exceção que representa um código de status HTTP 409.

import endpoints
import httplib

class ConflictException(endpoints.ServiceException):
  """Conflict exception that is mapped to a 409 response."""
  http_status = httplib.CONFLICT