Package google.rpc

Index

BadRequest

Beschreibt Verstöße in einer Clientanfrage. Bei diesem Fehlertyp geht es um die syntaktischen Aspekte der Anfrage.

Felder
field_violations[]

FieldViolation

Beschreibt alle Verstöße in einer Clientanfrage.

FieldViolation

Ein Nachrichtentyp, der verwendet wird, um ein einzelnes Feld mit ungültiger Anfrage zu beschreiben.

Felder
field

string

Ein Pfad, der zu einem Feld im Anfragetext führt. Der Wert ist eine Abfolge von durch Punkten getrennten Kennungen, die ein Protokollpufferfeld angeben.

Berücksichtige Folgendes:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

In diesem Beispiel kann field im Proto einen der folgenden Werte annehmen:

  • full_name für einen Verstoß im full_name-Wert
  • email_addresses[1].email für einen Verstoß im Feld email der ersten email_addresses-Nachricht
  • email_addresses[3].type[2] für einen Verstoß im zweiten type-Wert in der dritten email_addresses-Nachricht.

In JSON werden dieselben Werte so dargestellt:

  • fullName für einen Verstoß im fullName-Wert
  • emailAddresses[1].email für einen Verstoß im Feld email der ersten emailAddresses-Nachricht
  • emailAddresses[3].type[2] für einen Verstoß im zweiten type-Wert in der dritten emailAddresses-Nachricht.
description

string

Eine Beschreibung, warum das Anfrageelement schlecht ist.
reason

string

Der Grund für den Fehler auf Feldebene. Dies ist ein konstanter Wert, der die unmittelbare Ursache des Fehlers auf Feldebene angibt. Sie sollte den Typ des FieldViolation innerhalb des Bereichs von google.rpc.ErrorInfo.domain eindeutig identifizieren. Diese darf höchstens 63 Zeichen umfassen und mit dem regulären Ausdruck [A-Z][A-Z0-9_]+[A-Z0-9] für UPPER_SNAKE_CASE übereinstimmen.
localized_message

LocalizedMessage

Stellt eine lokalisierte Fehlermeldung für Fehler auf Feldebene bereit, die sicher an den API-Nutzer zurückgegeben werden kann.

Code

Die kanonischen Fehlercodes für gRPC APIs.

Manchmal können mehrere Fehlercodes zutreffen. Dienste sollten den spezifischsten Fehlercode liefern, der zutrifft. Beispiel: OUT_OF_RANGE sollte gegenüber FAILED_PRECONDITION bevorzugt werden, wenn beide Codes zutreffen. Entsprechend ist NOT_FOUND oder ALREADY_EXISTS gegenüber FAILED_PRECONDITION vorzuziehen.

Enums
OK

Kein Fehler; wird bei Erfolg angezeigt.

HTTP Mapping: 200 OK
CANCELLED

Der Vorgang wurde abgebrochen, üblicherweise vom Aufrufer.

HTTP Mapping: 499 Client Closed Request
UNKNOWN

Unbekannter Fehler. Dieser Fehler wird z. B. angezeigt, wenn ein von einem anderen Adressbereich erhaltener Status-Wert zu einem Fehlerbereich gehört, der in diesem Adressbereich nicht bekannt ist. Auch Fehler, die von APIs ausgelöst werden, die nicht genügend Fehlerinformationen liefern, können in diesen Fehler umgewandelt werden.

HTTP Mapping: 500 Internal Server Error
INVALID_ARGUMENT

Der Client hat ein ungültiges Argument angegeben. Dieser Wert ist nicht identisch mit FAILED_PRECONDITION. INVALID_ARGUMENT gibt Argumente an, die ungeachtet des Systemstatus problematisch sind (z. B. ein ungültiger Dateiname).

HTTP Mapping: 400 Bad Request
DEADLINE_EXCEEDED

Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Bei Vorgängen, die den Systemstatus verändern, kann dieser Fehler angezeigt werden, auch wenn der Vorgang erfolgreich abgeschlossen wurde. Zum Beispiel könnte eine erfolgreiche Antwort von einem Server so lange verzögert worden sein, dass die Frist abgelaufen ist.

HTTP Mapping: 504 Gateway Timeout
NOT_FOUND

Eine angeforderte Entität (z. B. Datei oder Verzeichnis) wurde nicht gefunden.

Hinweis für Serverentwickler: Wenn eine Anfrage, z. B. eine schrittweise Einführung von Funktionen oder eine undokumentierte Zulassungsliste, für eine gesamte Nutzerklasse abgelehnt wird, kann NOT_FOUND verwendet werden. Wenn eine Anfrage, z. B. nutzerbasierte Zugriffssteuerung, für einige Nutzer innerhalb einer Nutzerklasse abgelehnt wird, muss PERMISSION_DENIED verwendet werden.

HTTP Mapping: 404 Not Found
ALREADY_EXISTS

Die Entität, die ein Client erstellen wollte (z. B. eine Datei oder ein Verzeichnis), ist bereits vorhanden.

HTTP Mapping: 409 Conflict
PERMISSION_DENIED

Der Aufrufer hat keine Berechtigung zur Ausführung des angegebenen Vorgangs. PERMISSION_DENIED darf nicht für Ablehnungen verwendet werden, die dadurch verursacht werden, dass eine Ressource erschöpft ist (verwenden Sie stattdessen RESOURCE_EXHAUSTED für diese Fehler). PERMISSION_DENIED darf nicht verwendet werden, wenn der Aufrufer nicht ermittelt werden kann (verwenden Sie stattdessen UNAUTHENTICATED für diese Fehler). Dieser Fehlercode impliziert nicht, dass die Anfrage gültig ist oder die angefragte Entität existiert oder andere Vorbedingungen erfüllt.

HTTP Mapping: 403 Forbidden
UNAUTHENTICATED

Die Anfrage enthält keine gültigen Authentifizierungsanmeldedaten für diesen Vorgang.

HTTP Mapping: 401 Unauthorized
RESOURCE_EXHAUSTED

Eine Ressource, z. B. ein nutzerbezogenes Kontingent, ist erschöpft oder der Speicherplatz für das gesamte Dateisystem ist ausgegangen.

HTTP Mapping: 429 Too Many Requests
FAILED_PRECONDITION

Der Vorgang wurde abgelehnt, weil der Systemzustand nicht für die Ausführung des Vorgangs geeignet ist. Beispielsweise ist das zu löschende Verzeichnis nicht leer, ein rmdir-Vorgang wird auf eine Ressource angewendet, die kein Verzeichnis ist, usw.

Dienstimplementierungen können anhand der folgenden Richtlinien zwischen FAILED_PRECONDITION, ABORTED und UNAVAILABLE entscheiden: (a) Verwenden Sie UNAVAILABLE, wenn der Client nur den fehlgeschlagenen Aufruf wiederholen kann. (b) Verwenden Sie ABORTED, wenn der Client den Vorgang auf einer höheren Ebene wiederholen soll. Zum Beispiel, wenn ein vom Client angegebener Test- und Set-Wert fehlschlägt. Dies bedeutet, dass der Client eine Read-Modify-Write-Sequenz startet. (c) Sollte der Client den Fehler nicht wiederholen, bis der Systemstatus ausdrücklich festgelegt wurde, verwenden Sie FAILED_PRECONDITION. Wenn beispielsweise ein "rmdir" fehlschlägt, weil das Verzeichnis nicht leer ist, sollte FAILED_PRECONDITION angezeigt werden, da der Client den erneuten Versuch erst dann machen sollte, wenn die Dateien aus dem Verzeichnis gelöscht wurden.

HTTP Mapping: 400 Bad Request
ABORTED

Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Parallelitätsproblems wie einer fehlgeschlagenen Sequencer-Überprüfung oder einer abgebrochenen Transaktion.

Siehe obige Richtlinien zum Abwägen zwischen FAILED_PRECONDITION, ABORTED und UNAVAILABLE.

HTTP Mapping: 409 Conflict
OUT_OF_RANGE

Beim Vorgang wurde versucht, den gültigen Bereich zu überschreiten. Beispiel: Such- oder Lesevorgang über das Dateiende hinaus.

Im Gegensatz zu INVALID_ARGUMENT zeigt dieser Fehler ein Problem an, das behoben werden kann, wenn sich der Systemstatus ändert. Zum Beispiel erzeugt ein 32-Bit-Dateisystem INVALID_ARGUMENT, wenn es in einem Bereich lesen soll, der nicht innerhalb des Bereichs [0,2^32-1] liegt. Dagegen generiert es OUT_OF_RANGE, wenn für einen Bereich gelesen werden soll, der die aktuelle Dateigröße übersteigt.

Es gibt einige Überschneidungen zwischen FAILED_PRECONDITION und OUT_OF_RANGE. Wir empfehlen die Verwendung von OUT_OF_RANGE (der spezifischere Fehler), wenn dies zutrifft, damit die Aufrufer, die über einen Bereich iterieren, einfach nach einem OUT_OF_RANGE-Fehler suchen können, wenn sie fertig sind.

HTTP Mapping: 400 Bad Request
UNIMPLEMENTED

Dieser Vorgang ist nicht implementiert oder wird bei diesem Dienst nicht unterstützt bzw. ist bei diesem Dienst nicht aktiviert.

HTTP Mapping: 501 Not Implemented
INTERNAL

Interne Fehler. Das bedeutet, dass einige Invarianten, die vom zugrunde liegenden System erwartet werden, nicht erfüllt wurden. Dieser Fehlercode ist für schwerwiegende Fehler reserviert.

HTTP Mapping: 500 Internal Server Error
UNAVAILABLE

Der Dienst ist derzeit nicht verfügbar. Dies ist höchstwahrscheinlich ein vorübergehender Zustand, der durch Wiederholen mit einem Backoff korrigiert werden kann. Es ist nicht immer sicher, nicht idempotente Vorgänge zu wiederholen.

Siehe obige Richtlinien zum Abwägen zwischen FAILED_PRECONDITION, ABORTED und UNAVAILABLE.

HTTP Mapping: 503 Service Unavailable
DATA_LOSS

Dauerhafter Datenverlust oder Datenkorruption.

HTTP Mapping: 500 Internal Server Error

LocalizedMessage

Stellt eine lokalisierte Fehlermeldung bereit, die sicher an den Nutzer zurückgegeben werden kann und an einen RPC-Fehler angehängt werden kann.

Felder
locale

string

Das verwendete Gebietsschema gemäß der Spezifikation unter https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Beispiele: „en-US“, „fr-CH“, „es-MX“
message

string

Die übersetzte Fehlermeldung in der Sprache oben.

Status

Mit dem Typ Status wird ein logisches Fehlermodell definiert, das für verschiedene Programmierumgebungen wie REST APIs und RPC APIs geeignet ist. Dieses Modell wird von gRPC verwendet. Jede Status-Meldung enthält die folgenden drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails.

Weitere Informationen zu diesem Fehlermodell und zur Arbeit damit finden Sie in der API-Designanleitung.

Felder
code

int32

Der Statuscode, der idealerweise ein ENUM-Wert von google.rpc.Code ist.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede Fehlermeldung an den Nutzer sollte lokalisiert und im Feld google.rpc.Status.details gesendet werden. Sie kann auch clientseitig lokalisiert werden.
details[]

Any

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen allgemeinen Satz von Nachrichtentypen, die von APIs verwendet werden können.