Exceptions and HTTP status codes

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:

  throw 
  
 new 
  
 NotFoundException 
 ( 
 user 
 . 
 getEmail 
 ()); 
 

Exceptions provided by Endpoints Frameworks

Endpoints Frameworks provides the following exceptions, corresponding to specific HTTP status codes:

Supported HTTP status codes

Cloud Endpoints Frameworks supports a subset of HTTP status codes in API responses. The following table describes the supported codes.

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:

  import 
  
 com.google.api.server.spi.ServiceException 
 ; 
 // Exceptions must inherit from ServiceException 
 public 
  
 class 
 RequestTimeoutException 
  
 extends 
  
 ServiceException 
  
 { 
  
 public 
  
 RequestTimeoutException 
 ( 
 String 
  
 message 
 ) 
  
 { 
  
 super 
 ( 
 408 
 , 
  
 message 
 ); 
  
 } 
 } 
 

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 :

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