Excepciones y códigos de estado HTTP

En esta página se enumeran las excepciones proporcionadas por la biblioteca endpoints, así como los códigos de estado HTTP compatibles con Cloud Endpoints Frameworks.

En muchas situaciones, puede que quieras usar códigos de estado HTTP comunes para indicar si la solicitud de API de un usuario se ha completado correctamente o no. Por ejemplo, si un usuario intenta recuperar una entidad que no existe, puede enviar un código de estado HTTP 404 para indicar que no existe ninguna entidad con el ID entityId.

Puedes enviar códigos de estado HTTP comunes lanzando una excepción proporcionada por la biblioteca endpoints de la siguiente manera:

throw new NotFoundException(user.getEmail());

Excepciones proporcionadas por Endpoints Frameworks

Endpoints Frameworks proporciona las siguientes excepciones, que corresponden a códigos de estado HTTP específicos:

Excepción	Código de estado HTTP correspondiente
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

Códigos de estado HTTP admitidos

Cloud Endpoints Frameworks admite un subconjunto de códigos de estado HTTP en las respuestas de las APIs. En la siguiente tabla se describen los códigos admitidos.

Códigos de estado de HTTP	Asistencia
HTTP 2xx	Endpoints Frameworks suele asumir el código HTTP 200 si el método de la API se devuelve correctamente. Si el tipo de respuesta del método de la API es void o el valor devuelto del método de la API es null , se asigna el código HTTP 204.
HTTP 3xx	No se admiten los códigos 3xx de HTTP. Si se usa cualquier código HTTP 3xx, se devuelve una respuesta HTTP 404.
HTTP 4xx	Solo se admiten los siguientes códigos HTTP 4xx: 400 401 403 404 409 410 412 413 Cualquier otro código HTTP 4xx se devuelve como error 404, excepto los siguientes: 405 se devuelve como 501 408 se devuelve como 503
HTTP 5xx	Todos los códigos de estado HTTP 5xx se convierten en HTTP 503 en la respuesta del cliente.

Importante: No uses clases de excepciones personalizadas para devolver códigos HTTP 2xx. Endpoints Frameworks no admite que se devuelva el código HTTP 201 ni ningún otro código 2xx, excepto los códigos HTTP 200 y HTTP 204, tal como se describe en la tabla anterior.

Crear tus propias clases de excepción

Si quieres crear otras clases de excepción para otros códigos de estado HTTP, debes crear una subclase de com.google.api.server.spi.ServiceException. En el siguiente fragmento se muestra cómo crear una clase de excepción que representa un código de estado 408 HTTP:

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

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

Importante: Si se produce una excepción no controlada en tu aplicación, se generará un error HTTP 503 en tu API de Cloud Endpoints, a menos que extienda com.google.api.server.spi.ServiceException.

Usar códigos de estado HTTP no admitidos

Es posible usar códigos de estado HTTP que no estén en la lista anterior. Ten en cuenta que, si decides hacerlo, puede que tenga consecuencias no deseadas para las bibliotecas de cliente que accedan a la API. Para usar códigos de error no admitidos, crea tu propia clase de excepción, tal como se describe en la sección anterior, y añade un nuevo parámetro de inicialización de servlet enableExceptionCompatibility a 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>