Ausnahmen und HTTP-Statuscodes

Auf dieser Seite sind die Ausnahmen aufgelistet, die von der endpoints-Bibliothek zur Verfügung gestellt werden, sowie die von Cloud Endpoints Frameworks unterstützten HTTP-Statuscodes.

In vielen Situationen möchten Sie vielleicht gängige HTTP-Statuscodes verwenden, um einem Nutzer anzuzeigen, ob seine API-Anfrage erfolgreich war oder nicht. Wenn ein Nutzer beispielsweise versucht, eine nicht vorhandene Entität abzurufen, können Sie einen HTTP-404-Statuscode senden und damit mitteilen, dass keine Entität mit der ID entityIdvorhanden ist.

Zum Senden gängiger HTTP-Statuscodes können Sie wie folgt eine von der endpoints-Bibliothek bereitgestellte Ausnahme auslösen:

throw new NotFoundException(user.getEmail());

Von Endpoints Frameworks ausgegebene Ausnahmen

Endpoints Frameworks gibt die folgenden Ausnahmen aus. Diese entsprechen spezifischen HTTP-Statuscodes:

Ausnahme Zugehöriger HTTP-Statuscode
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

Unterstützte HTTP-Statuscodes

Cloud Endpoints Frameworks unterstützt in API-Antworten einen Teil der HTTP-Statuscodes. Die unterstützten Codes werden in der folgenden Tabelle beschrieben.

HTTP-Statuscodes Unterstützung
HTTP 2xx Endpoints Frameworks geht bei einer erfolgreichen Rückgabe der API-Methode normalerweise von HTTP 200 aus.
Wenn der Antworttyp der API-Methode void oder der Rückgabewert der API-Methode null ist, wird stattdessen HTTP 204 festgelegt.
HTTP 3xx HTTP 3xx-Codes werden nicht unterstützt. Bei der Verwendung von HTTP 3xx-Codes wird HTTP 404 zurückgegeben.
HTTP 4xx Es werden nur die folgenden HTTP 4xx-Codes unterstützt:
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
Für alle anderen HTTP 4xx-Codes wird der Fehler 404 zurückgegeben. Dies gilt jedoch nicht für die folgenden Codes:
  • Für 405 wird 501 zurückgegeben.
  • Für 408 wird 503 zurückgegeben.
HTTP 5xx Alle HTTP 5xx-Statuscodes werden in der Client-Antwort in HTTP 503 konvertiert.

Eigene Ausnahmeklassen erstellen

Wenn Sie für andere HTTP-Statuscodes andere Ausnahmeklassen erstellen möchten, müssen Sie dazu abgeleitete Klassen von com.google.api.server.spi.ServiceException erstellen. Das folgende Snippet zeigt, wie Sie eine Ausnahmeklasse erstellen, die den Statuscode HTTP 408 repräsentiert:

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

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

Nicht unterstützte HTTP-Statuscodes verwenden

Sie können auch HTTP-Statuscodes verwenden, die nicht in der obigen Liste der unterstützten Codes enthalten sind. Beachten Sie, dass in diesem Fall nicht beabsichtigte Folgen für Clientbibliotheken mit Zugriff auf die API entstehen können. Wenn Sie nicht unterstützte Fehlercodes verwenden möchten, erstellen Sie wie im vorherigen Abschnitt beschrieben eine eigene Ausnahmeklasse und fügen Sie einen neuen Servlet-Initialisierungsparameter enableExceptionCompatibility zu EndpointsServlet hinzu.

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