Cette page a été traduite par l'API Cloud Translation.
Switch to English

Exceptions et codes d'état HTTP

Cette page répertorie les exceptions fournies par la bibliothèque endpoints, ainsi que les codes d'état HTTP compatibles avec Cloud Endpoints Frameworks.

Dans la plupart des cas, vous devez utiliser des codes d'état HTTP courants pour indiquer le succès ou l'échec d'une requête API. Par exemple, si un utilisateur tente de récupérer une entité qui n'existe pas, vous pouvez envoyer un code d'état HTTP 404 indiquant qu'il n'existe aucune entité correspondant à l'ID entityId.

Vous pouvez envoyer des codes d'état HTTP courants en insérant une exception fournie par la bibliothèque endpoints, comme suit :

throw new NotFoundException(user.getEmail());

Exceptions fournies par Endpoints Frameworks

Endpoints Frameworks fournit les exceptions suivantes, correspondant à des codes de statut HTTP spécifiques :

Exception Code d'état HTTP correspondant
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

Codes d'état HTTP compatibles

Cloud Endpoints Frameworks est compatible avec un sous-ensemble de codes d'état HTTP dans les réponses d'API. Le tableau suivant décrit les codes compatibles.

Codes d'état HTTP Compatibilité
HTTP 2xx Le code HTTP 200 est généralement utilisé par Endpoints Frameworks lorsque la méthode API aboutit.
Si la réponse de la méthode API est du type void ou si la valeur renvoyée est null, le code HTTP 204 est utilisé à la place.
HTTP 3xx Les codes HTTP 3xx ne sont pas compatibles. L'utilisation de tels codes entraîne une réponse HTTP 404.
HTTP 4xx Seuls les codes HTTP 4xx suivants sont compatibles :
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
Tous les autres codes HTTP 4xx sont renvoyés en tant qu'erreurs 404, à l'exception des codes suivants :
  • Le code HTTP 405 est renvoyé en tant qu'erreur 501.
  • Le code HTTP 408 est renvoyé en tant qu'erreur 503.
HTTP 5xx Tous les codes d'état HTTP 5xx sont convertis en HTTP 503 dans la réponse du client.

Créer vos propres classes d'exceptions

Si vous souhaitez créer des classes d'exceptions pour d'autres codes d'état HTTP, vous pouvez le faire en définissant des sous-classes de com.google.api.server.spi.ServiceException. L'extrait de code suivant montre comment créer une classe d'exceptions qui représente un code d'état 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);
  }
}

Utiliser des codes d'état HTTP non compatibles

Il est possible d'utiliser des codes d'état HTTP qui ne figurent pas dans la liste ci-dessus. Notez que cela peut avoir des conséquences inattendues pour les bibliothèques clientes qui accèdent à l'API. Pour utiliser des codes d'erreur non compatibles, créez votre propre classe d'exceptions comme indiqué à la section précédente, et ajoutez le paramètre d'initialisation enableExceptionCompatibility au servlet 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>