Exceptions and HTTP

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.

Important: An uncaught exception in your application will result in an HTTP 503
error from your Endpoints API.

You can send such common HTTP status codes by raising an exception provided
by the endpoints library as follows:

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:

400

401

403

404

409

410

412

413

Any other HTTP 4xx codes will be returned as error 404, except for the following:

405 is returned as 501

408 is returned as 503

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: