Fehler

Dieses Kapitel bietet einen Überblick über das Fehlermodell für Google APIs. Entwickler erhalten außerdem eine allgemeine Anleitung zur richtigen Fehlergenerierung und -behebung.

Google APIs verwenden ein einfaches protokollunabhängiges Fehlermodell, das es ermöglicht, eine konsistente Umgebung innerhalb unterschiedlicher APIs, API-Protokolle wie gRPC oder HTTP und Fehlerkontexte (z. B. Asynchronitäten, Batch- oder Workflow-Fehler) zu schaffen.

Fehlermodell

Das Fehlermodell wird logisch durch google.rpc.Status definiert. Bei einem API-Fehler wird eine solche Instanz an den Client zurückgegeben. Das folgende Code-Snippet zeigt den allgemeinen Aufbau des Fehlermodells:

package google.rpc;

message Status {
  // A simple error code that can be easily handled by the client. The
  // actual error code is defined by `google.rpc.Code`.
  int32 code = 1;

  // A developer-facing human-readable error message in English. It should
  // both explain the error and offer an actionable resolution to it.
  string message = 2;

  // Additional error information that the client code can use to handle
  // the error, such as retry delay or a help link.
  repeated google.protobuf.Any details = 3;
}

Da die meisten Google APIs ein ressourcenorientiertes API-Design verwenden, erfolgt auch die Fehlerbehebung nach diesem Designprinzip. Dabei wird ein kleiner Satz von Standardfehlern für eine große Anzahl von Ressourcen genutzt. Anstatt zum Beispiel verschiedene Arten von "Nicht gefunden"-Fehlern zu definieren, verwendet der Server den Standardfehlercode google.rpc.Code.NOT_FOUND und teilt dem Client mit, welche Ressource nicht gefunden wurde. Der verhältnismäßig kleine Zustandsbereich vereinfacht die Dokumentation und die Clientlogik. Außerdem sind bessere idiomatische Zuordnungen in Clientbibliotheken möglich und umsetzbare Informationen lassen sich uneingeschränkt einbeziehen.

Fehlercodes

Google APIs müssen die von google.rpc.Code definierten kanonischen Fehlercodes enthalten. In den einzelnen APIs sollten keine zusätzlichen Fehlercodes definiert werden, da Entwickler in der Regel keine Logiken zur Verarbeitung einer großen Anzahl von Fehlercodes schreiben. Beispiel: Bei der Verarbeitung von durchschnittlich drei Fehlercodes pro API-Aufruf würde der Großteil der Anwendungslogik nur für die Fehlerbehebung genutzt werden, was für keine gute Entwicklerumgebung spricht.

Fehlermeldungen

Fehlermeldungen sollen Nutzern helfen, API-Fehler schnell und einfach zu verstehen und zu beheben. Beachten Sie beim Schreiben von Fehlermeldungen generell die folgenden Richtlinien:

  • Gehen Sie nicht davon aus, dass Nutzer API-Experten sind. Nutzer können Cliententwickler, Betriebspersonal, IT-Mitarbeiter oder Endnutzer von Anwendungen sein.
  • Gehen Sie nicht davon aus, dass Nutzer etwas über Ihre Dienstimplementierung wissen oder mit Fehlerkontexten wie etwa Log-Analysen vertraut sind.
  • Fehlermeldungen sollten nach Möglichkeit so konstruiert sein, dass auch technische Nutzer, die keine Entwickler Ihrer API sind, auf den Fehler reagieren und ihn beheben können.
  • Halten Sie Fehlermeldungen kurz. Geben Sie bei Bedarf einen Link an, über den Nutzer Fragen stellen, Feedback geben oder weitere Informationen erhalten können, die den Rahmen der Fehlermeldung an sich sprengen würden. Verwenden Sie andernfalls das erweiterbare Detailfeld.

Fehlerdetails

Google APIs definieren eine Reihe standardmäßiger Fehlernutzlasten für Fehlerdetails. Sie finden diese unter google/rpc/error_details.proto. Fehlerdetails decken die gängigsten Anforderungen für API-Fehler wie Kontingentfehler und ungültige Parameter ab. Verwenden Sie für Fehlerdetails nach Möglichkeit ebenso wie für Fehlercodes die Standardnutzlasten.

Zusätzliche Fehlerdetailtypen sollten nur eingeführt werden, wenn sie ergänzend zum Anwendungscode zur Fehlerbehebung beitragen. Wenn die Fehlerinformationen nur von Nutzern verarbeitet werden, geben Sie den Fehlermeldungsinhalt an und lassen Sie Entwickler den Fehler manuell beheben, anstatt neue Fehlerdetailtypen einzuführen.

Hier ein paar Beispiele für Nutzlasten vom Typ error_details:

  • RetryInfo beschreibt, wann Clients eine fehlgeschlagene Anfrage wiederholen können. Die Rückgabe erfolgt gegebenenfalls bei Code.UNAVAILABLE oder Code.ABORTED
  • QuotaFailure beschreibt, wie eine Kontingentprüfung fehlgeschlagen ist. Die Rückgabe erfolgt gegebenenfalls bei Code.RESOURCE_EXHAUSTED
  • BadRequest beschreibt Verstöße in einer Clientanfrage. Die Rückgabe erfolgt gegebenenfalls bei Code.INVALID_ARGUMENT

HTTP-Zuordnung

Während Proto3-Nachrichten einen nativen JSON-Codierung haben, verwendet die Google API Platform aus Gründen der Abwärtskompatibilität ein anderes Fehlerschema für Google REST APIs.

Schema:

// The error schema for Google REST APIs. NOTE: this schema is not used for
// other wire protocols.
message Error {
  // This message has the same semantics as `google.rpc.Status`. It has an extra
  // field `status` for backward compatibility with Google API Client Library.
  message Status {
    // This corresponds to `google.rpc.Status.code`.
    int32 code = 1;
    // This corresponds to `google.rpc.Status.message`.
    string message = 2;
    // This is the enum version for `google.rpc.Status.code`.
    google.rpc.Code status = 4;
    // This corresponds to `google.rpc.Status.details`.
    repeated google.protobuf.Any details = 5;
  }
  // The actual error payload. The nested message structure is for backward
  // compatibility with Google API client libraries. It also makes the error
  // more readable to developers.
  Status error = 1;
}

Beispiel:

{
  "error": {
    "code": 401,
    "message": "Request had invalid credentials.",
    "status": "UNAUTHENTICATED",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.RetryInfo",
      ...
    }]
  }
}

RPC-Zuordnung

Das Fehlermodell wird von unterschiedlichen RPC-Protokollen auf unterschiedliche Weise zugeordnet. Hinsichtlich gRPC wird das Fehlermodell nativ durch den generierten Code und die Laufzeitbibliothek in den verfügbaren Sprachen unterstützt. Weitere Informationen finden Sie in der API-Dokumentation für gRPC, z. B. im Abschnitt zu io.grpc.Status.

Clientbibliothek-Zuordnung

Google-Clientbibliotheken können Fehler je nach Sprache unterschiedlich wiedergeben, um den gängigen Dialekten gerecht zu werden. Die Bibliothek google-cloud-go gibt beispielsweise einen Fehler zurück, der dieselbe Schnittstelle wie google.rpc.Status implementiert, während google-cloud-java eine Ausnahme auslöst.

Fehlerlokalisierung

Das Feld message in google.rpc.Status ist Entwicklern vorbehalten und muss auf Englisch sein.

Für nutzerseitige Fehlermeldungen verwenden Sie google.rpc.LocalizedMessage als Detailfeld. Das Meldungsfeld in google.rpc.LocalizedMessage kann lokalisiert werden. Achten Sie darauf, dass das Meldungsfeld in google.rpc.Status auf Englisch ist.

Standardmäßig sollte der API-Dienst die für die Lokalisierung zu verwendende Sprache anhand des Gebietsschemas des authentifizierten Nutzers oder des HTTP-Headers Accept-Language ermitteln.

Fehlerbehebung

In der nachfolgenden Tabelle sind alle gRPC-Fehlercodes aufgeführt, die in google.rpc.Code definiert wurden. Außerdem erhalten Sie eine kurze Beschreibung der Fehlerursache. Zur Fehlerbehebung können Sie die Beschreibung des zurückgegebenen Statuscodes prüfen und den Aufruf entsprechend ändern.

HTTP RPC Beschreibung
200 OK Kein Fehler
400 INVALID_ARGUMENT Der Client hat ein ungültiges Argument angegeben. Weitere Informationen finden Sie in der Fehlermeldung und den Fehlerdetails.
400 FAILED_PRECONDITION Die Anfrage, wie etwa das Löschen eines Verzeichnisses mit Inhalt, kann im aktuellen Systemzustand nicht ausgeführt werden.
400 OUT_OF_RANGE Der Client hat einen ungültigen Bereich angegeben.
401 UNAUTHENTICATED Die Anfrage konnte aufgrund eines fehlenden, ungültigen oder abgelaufenen OAuth-Tokens nicht authentifiziert werden.
403 PERMISSION_DENIED Der Client verfügt nicht über die erforderliche Berechtigung. Dies kann vorkommen, wenn das OAuth-Token nicht über die richtigen Bereiche verfügt, der Client keine Berechtigung besitzt oder die API nicht für das Clientprojekt aktiviert wurde.
404 NOT_FOUND Eine angegebene Ressource wurde nicht gefunden oder die Anfrage wurde ohne Angabe von Gründen abgelehnt, beispielsweise, weil die Ressource auf die weiße Liste gesetzt wurde.
409 ABORTED Gibt einen Konflikt aufgrund von gleichzeitig ausgeführten Aktionen an, wie etwa einen Read-Modify-Write-Konflikt.
409 ALREADY_EXISTS Die von einem Client zu erstellende Ressource ist bereits vorhanden.
429 RESOURCE_EXHAUSTED Entweder wurde das Ressourcenkontingent überschritten oder das Ratenlimit erreicht. Der Client sollte in den Fehlerdetails zu google.rpc.QuotaFailure nach weiteren Informationen suchen.
499 CANCELLED Request cancelled by the client.
500 DATA_LOSS Dauerhafter Datenverlust oder Datenkorruption. Der Client sollte den Fehler dem Nutzer melden.
500 UNKNOWN Unbekannter Serverfehler. In der Regel ein Serverprogrammfehler.
500 INTERNAL Interner Serverfehler. In der Regel ein Serverprogrammfehler.
501 NOT_IMPLEMENTED Die API-Methode wurde vom Server nicht implementiert.
503 UNAVAILABLE Dienst nicht verfügbar. In der Regel ist der Server ausgefallen.
504 DEADLINE_EXCEEDED Die Frist der Anfrage wurde überschritten. Dies geschieht nur, wenn für den Aufruf eine Frist festgelegt wurde, die kürzer ist als die Standardfrist der Methode (d. h., die angeforderte Frist reicht nicht aus, damit der Server die Anfrage bearbeitet), und die Anfrage nicht innerhalb der Frist abgeschlossen wurde.

Wiederholungen nach Fehlern

Clients sollten Vorgänge nach den Fehlern 500 und 503 mit exponentiellem Backoff wiederholen. Die Mindestverzögerung sollte 1 Sekunde betragen, sofern nicht anders angegeben. Beim Fehler 429 kann der Client den Vorgang mit einer Mindestverzögerung von 30 Sekunden wiederholen. Bei allen anderen Fehlern ist eventuell keine Wiederholung möglich. Prüfen Sie zuerst, ob die Anfrage idempotent ist, und lesen Sie die Fehlermeldung, um weitere Informationen zu erhalten.

Fehlerfortpflanzung

Wenn der API-Dienst von anderen Diensten abhängt, sollten Sie Fehler von diesen Diensten nicht ungesehen an Ihre Clients weitergeben. Wir empfehlen beim Übersetzen von Fehlern Folgendes:

  • Blenden Sie Details zur Implementierung sowie vertrauliche Informationen aus.
  • Passen Sie die für den Fehler zuständige Partei an. Beispielsweise sollte ein Server, der von einem anderen Dienst den Fehler INVALID_ARGUMENT empfängt, an seinen eigenen Aufrufer den Fehler INTERNAL weiterleiten.

Fehler generieren

Wenn Sie Serverentwickler sind, sollten Sie Fehler mit ausreichenden Informationen generieren, damit Cliententwickler das Problem verstehen und beheben können. Gleichzeitig müssen Sie die Sicherheit und Vertraulichkeit der Nutzerdaten berücksichtigen und die Offenlegung vertraulicher Informationen in der Fehlermeldung und den Fehlerdetails vermeiden. Der Grund dafür ist, dass Fehler häufig protokolliert werden und gegebenenfalls für andere Nutzer zugänglich sind. Eine Fehlermeldung wie "Client IP address is not on whitelist 128.0.0.0/8" legt beispielsweise Informationen über die serverseitige Richtlinie offen, auf die der Nutzer normalerweise keinen Zugriff hat.

Für eine ordnungsgemäße Fehlergenerierung müssen Sie mit google.rpc.Code vertraut sein, um für jede Fehlerbedingung den passenden Fehlercode auszuwählen. Eine Serveranwendung kann mehrere Fehlerbedingungen parallel prüfen und die erste zurückgeben.

In der folgenden Tabelle sind die Fehlercodes mit je einem Beispiel einer guten Fehlermeldung aufgeführt.

HTTP RPC Beispiel für Fehlermeldung
400 INVALID_ARGUMENT Request field x.y.z is xxx, expected one of [yyy, zzz].
400 FAILED_PRECONDITION Resource xxx is a non-empty directory, so it cannot be deleted.
400 OUT_OF_RANGE Parameter 'age' is out of range [0, 125].
401 UNAUTHENTICATED Invalid authentication credentials.
403 PERMISSION_DENIED Permission 'xxx' denied on file 'yyy'.
404 NOT_FOUND Resource 'xxx' not found.
409 ABORTED Couldn’t acquire lock on resource ‘xxx’.
409 ALREADY_EXISTS Resource 'xxx' already exists.
429 RESOURCE_EXHAUSTED Quota limit 'xxx' exceeded.
499 CANCELLED Request cancelled by the client.
500 DATA_LOSS See note.
500 UNKNOWN See note.
500 INTERNAL See note.
501 NOT_IMPLEMENTED Method 'xxx' not implemented.
503 UNAVAILABLE See note.
504 DEADLINE_EXCEEDED See note.

Hinweis: Da der Client den Serverfehler nicht beheben kann, bringt es nichts, zusätzliche Fehlerdetails zu generieren. Damit keine vertraulichen Informationen unter Fehlerbedingungen offengelegt werden, sollten keine Fehlermeldungen, sondern nur die Fehlerdetails google.rpc.DebugInfo generiert werden. Die DebugInfo gilt ausschließlich für serverseitiges Logging und darf nicht an den Client gesendet werden.

Das Paket google.rpc definiert eine Reihe standardmäßiger Fehlernutzlasten, die benutzerdefinierten Fehlernutzlasten vorgezogen werden. In der folgenden Tabelle sind die Fehlercodes und deren standardmäßige Fehlernutzlast aufgelistet, falls zutreffend.

HTTP RPC Empfohlenes Fehlerdetail
400 INVALID_ARGUMENT google.rpc.BadRequest
400 FAILED_PRECONDITION google.rpc.PreconditionFailure
400 OUT_OF_RANGE google.rpc.BadRequest
401 UNAUTHENTICATED
403 PERMISSION_DENIED
404 NOT_FOUND google.rpc.ResourceInfo
409 ABORTED
409 ALREADY_EXISTS google.rpc.ResourceInfo
429 RESOURCE_EXHAUSTED google.rpc.QuotaFailure
499 CANCELLED
500 DATA_LOSS
500 UNKNOWN
500 INTERNAL
501 NOT_IMPLEMENTED
503 UNAVAILABLE
504 DEADLINE_EXCEEDED
Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...