This page lists the exceptions provided by the `endpoints` library as well as
HTTP status codes supported by Cloud Endpoints Frameworks.

In many situations, you might 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 doesn't exist, you might want to send an
HTTP `404` status code to say that no entity exists with ID: `entityId`.

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

```java
throw new NotFoundException(user.getEmail());
```

## Exceptions provided by Endpoints Frameworks

Endpoints Frameworks 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

Cloud Endpoints Frameworks 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 Frameworks 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` is set instead. |
| HTTP 3xx | HTTP 3xx codes aren't supported. Use of any HTTP 3xx codes results in an HTTP `404` response. |
| HTTP 4xx | Only the following HTTP 4xx codes are supported: - `400` - `401` - `403` - `404` - `409` - `410` - `412` - `413` Any other HTTP 4xx codes are 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 HTTP `503` in the client response. |

> [!IMPORTANT]
> **Important:** Don't use custom exception classes to return HTTP 2xx codes. Endpoints Frameworks doesn't support returning HTTP `201` or any other 2xx codes except HTTP `200` and HTTP `204` as described in the preceding table.

## Creating your own exception classes

If you want to create other exception classes for other HTTP status codes, you
need to subclass `com.google.api.server.spi.ServiceException`. The
following snippet shows how to create an exception class that represents an
HTTP `408` status code:

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

// Exceptions must inherit from ServiceException
public class RequestTimeoutException extends ServiceException {
  public RequestTimeoutException(String message) {
    super(408, message);
  }
}
```

> [!IMPORTANT]
> **Important:** An uncaught exception in your application results in an HTTP `503` error from your Cloud Endpoints API, unless it extends `com.google.api.server.spi.ServiceException`.

## Using unsupported HTTP status codes

It is possible to use HTTP status codes that aren't in the preceding supported
list. Note that if you decide to do so, it might have unintended consequences
for client libraries that access the API. To use unsupported error codes,
create your own exception class, as described in the previous section, and
add a new servlet initialization parameter `enableExceptionCompatibility` to
`EndpointsServlet`:

```java
  <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>
```