We recommend that you use the latest version of this feature, which is renamed to Cloud Endpoints Frameworks for App Engine. This new version supports App Engine standard environment, provides lower latency, and has better integration with App Engine. For more details, see Migrating to 2.0.
In many situations, you may want to use common HTTP status codes to indicate
the success or failure of a user's API request. For example, if a user is
attempting to retrieve an entity which does not exist, you may want to send an
HTTP 404 status code saying No entity with the ID entity_id exists.
You can send such common HTTP status codes by raising an exception provided by the endpoints library as follows:
message = 'No entity with the id "%s" exists.' % entity_id
raise endpoints.NotFoundException(message)
Exceptions Provided by Endpoints
The endpoints library provides the following exceptions, corresponding to specific HTTP status codes:
| Exception | Corresponding HTTP Status Code |
|---|---|
endpoints.BadRequestException |
HTTP 400 |
endpoints.UnauthorizedException |
HTTP 401 |
endpoints.ForbiddenException |
HTTP 403 |
endpoints.NotFoundException |
HTTP 404 |
endpoints.InternalServerErrorException |
HTTP 500 |
Supported HTTP Status Codes
Endpoints supports a subset of HTTP status codes in API responses. The following table describes the supported codes.
| HTTP Status Codes | Support |
|---|---|
| HTTP 2xx | HTTP 200 is typically assumed by Endpoints if the API method returns successfully.If the API method response type is VoidMessage or the return value of the API method is None , HTTP 204 will be set instead.HTTP 2xx codes should not be used in custom exception classes. |
| HTTP 3xx | HTTP 3xx codes are not supported. Use of any HTTP 3xx codes will result in an HTTP 404 response. |
| HTTP 4xx | Only the HTTP 4xx codes listed below are supported:
|
| HTTP 5xx | All HTTP 5xx status codes are converted to be HTTP 503 in the client response. |
Creating Your Own Exception Classes
If you want to create other exception classes for other HTTP status codes, you
can do so by subclassing endpoints.ServiceException. The following snippet
shows how to create an exception class that represents an HTTP 409 status code:
import endpoints
import httplib
class ConflictException(endpoints.ServiceException):
"""Conflict exception that is mapped to a 409 response."""
http_status = httplib.CONFLICT
