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 exists with ID: entityId.

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

String message = "No entity exists with ID: " + entityId;
throw new NotFoundException(message);

Exceptions Provided by Endpoints

The endpoints library provides the following exceptions, corresponding to specific HTTP status codes:

Exception	Corresponding HTTP Status Code
`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

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 `void` or the return value of the API method is `null`, 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 com.google.api.server.spi.ServiceException. The following snippet shows how to create an exception class that represents an HTTP 408 status code:

import com.google.api.server.spi.ServiceException;

public class RequestTimeoutException extends ServiceException {
    public RequestTimeoutException(String message) {
        super(408, message);
    }
}

Important: An uncaught exception in your application will result in an HTTP 503 error from your Endpoints API, unless it extends com.google.api.server.spi.ServiceException.

10 April 2024