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.

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);
  }
}

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>