Excepciones y códigos de estado HTTP

En esta página, se enumeran las excepciones proporcionadas por la biblioteca de endpoints y los códigos de estado HTTP que admite Cloud Endpoints Frameworks.

En muchas situaciones, es posible que desees utilizar códigos de estado HTTP comunes para indicar si la solicitud a la API de un usuario se realizó correctamente o si hubo un error. Por ejemplo, si un usuario intenta recuperar una entidad que no existe, es posible que desees enviar un código de estado HTTP 404 para decir que no existe ninguna entidad con ID: entityId.

Puedes enviar códigos de estado HTTP comunes mediante una excepción provista con la biblioteca de endpoints de la siguiente manera:

throw new NotFoundException(user.getEmail());

Excepciones proporcionadas por Endpoints Frameworks

Endpoints Frameworks proporciona las siguientes excepciones, correspondientes 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 compatibles

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

Códigos de estado HTTP	Asistencia
HTTP 2xx	HTTP 200 generalmente es el que se supone en Endpoints Frameworks si el método de API es correcto. Si el tipo de respuesta del método API es void o el valor mostrado del método API es null, en su lugar se establece HTTP 204.
HTTP 3xx	Los códigos HTTP 3xx no son compatibles. El uso de cualquier código HTTP 3xx da como resultado 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 muestra como error 404, excepto por lo siguiente: 405 se muestra como 501. 408 se muestra 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 mostrar códigos HTTP 2xx. Endpoints Frameworks no admite mostrar HTTP 201 o ningún otro código 2xx excepto HTTP 200 y HTTP 204, como se describe en la tabla anterior.

Crea tus propias clases de excepciones

Si quieres crear clases de excepción diferentes para otros códigos de estado HTTP, debes crear la subclase com.google.api.server.spi.ServiceException. El fragmento siguiente muestra cómo crear una clase de excepción que represente un código de estado HTTP 408:

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: Una excepción no detectada en tu aplicación da como resultado un error HTTP 503 de tu API de Cloud Endpoints, a menos que se extienda com.google.api.server.spi.ServiceException.

Utiliza códigos de estado HTTP no compatibles

Es posible usar códigos de estado HTTP que no se encuentran en la lista compatible anterior. Ten en cuenta que si decides hacerlo, podrías tener consecuencias no deseadas para las bibliotecas cliente que acceden a la API. A fin de usar códigos de error no compatibles, crea tu propia clase de excepción, como se describe en la sección anterior, y agrega un nuevo parámetro de inicialización del servlet enableExceptionCompatibility para EndpointsServlet de la siguiente manera:

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