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.

Hier einige Tipps:

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

  • 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

Enthält eine lokalisierte Fehlermeldung für Fehler auf Feldebene, 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. z. B. wenn ein vom Client angegebener Test- und Set-Wert fehlschlägt. Dies bedeutet, dass der Client eine Read-Modify-Write-Sequenz neu starten sollte. (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

Fehlerinformation

Beschreibt die Ursache des Fehlers mit strukturierten Details.

Beispiel für einen Fehler beim Kontaktieren der API „pubsub.googleapis.com“, wenn sie nicht aktiviert ist:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

Diese Antwort gibt an, dass die pubsub.googleapis.com API nicht aktiviert ist.

Beispiel für einen Fehler, der zurückgegeben wird, wenn versucht wird, eine Spanner-Instanz in einer Region zu erstellen, in der keine Ressourcen verfügbar sind:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
Felder
reason

string

Der Grund für den Fehler. Dies ist ein konstanter Wert, der die unmittelbare Ursache des Fehlers angibt. Fehlerursachen sind innerhalb einer bestimmten Fehlerdomain eindeutig. 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.
domain

string

Die logische Gruppierung, zu der der "reason" gehört. Die Fehlerdomain ist in der Regel der registrierte Dienstname des Tools oder Produkts, das den Fehler generiert. Beispiel: „pubsub.googleapis.com“. Wenn der Fehler von einer gemeinsamen Infrastruktur generiert wird, muss die Fehlerdomain ein weltweit eindeutiger Wert sein, der die Infrastruktur identifiziert. Bei der Google API-Infrastruktur ist die Fehlerdomain „googleapis.com“.
metadata

map<string, string>

Zusätzliche strukturierte Details zu diesem Fehler.

Schlüssel müssen dem regulären Ausdruck [a-z][a-zA-Z0-9-_]+ entsprechen, sollten aber idealerweise in lowerCamelCase geschrieben sein. Außerdem dürfen sie maximal 64 Zeichen lang sein. Wenn der aktuelle Wert eines überschrittenen Limits benannt wird, sollten die Einheiten im Schlüssel enthalten sein, nicht im Wert. Beispielsweise sollte {"instanceLimitPerRequest": "100"} anstelle von {"instanceLimit": "100/request"} zurückgegeben werden, wenn der Client die Anzahl der Instanzen überschreitet, die in einer einzelnen Batchanfrage erstellt werden können.

Hilfe

Bietet Links zur Dokumentation oder zum Ausführen einer Out-of-Band-Aktion.

Wenn beispielsweise eine Kontingentprüfung mit einem Fehler fehlgeschlagen ist, der darauf hinweist, dass der aufrufende Dienst den aufgerufenen Dienst nicht aktiviert hat, kann dies eine URL enthalten, die direkt zum richtigen Ort in der Entwicklerkonsole verweist, um das Bit zu ändern.

Felder

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.

PreconditionFailure

Beschreibt, welche Vorbedingungen nicht erfüllt wurden.

Wenn ein RPC beispielsweise fehlgeschlagen ist, weil die Nutzungsbedingungen bestätigt werden mussten, könnte der Verstoß gegen die Nutzungsbedingungen in der PreconditionFailure-Meldung aufgeführt werden.

Felder
violations[]

Violation

Beschreibt alle Verstöße gegen die Vorbedingungen.

Verstoß

Ein Nachrichtentyp, der verwendet wird, um einen einzelnen Fehler bei einer Vorbedingung zu beschreiben.

Felder
type

string

Der Typ von PreconditionFailure. Wir empfehlen, einen dienstspezifischen Enum-Typ zu verwenden, um die unterstützten Themen für Precondition-Verstöße zu definieren. Beispiel: „NUB“ für „Verstoß gegen die Nutzungsbedingungen“.
subject

string

Das Subjekt, das je nach Typ fehlgeschlagen ist. Beispiel: „google.com/cloud“ relativ zum Typ „Nutzungsbedingungen“ gibt an, auf welche Nutzungsbedingungen verwiesen wird.
description

string

Eine Beschreibung, wie die Voraussetzung fehlgeschlagen ist. Anhand dieser Beschreibung können Entwickler nachvollziehen, wie sie den Fehler beheben können.

Beispiel: „Nutzungsbedingungen nicht akzeptiert“.

QuotaFailure

Beschreibt, wie eine Kontingentprüfung fehlgeschlagen ist.

Wenn beispielsweise ein Tageslimit für das aufrufende Projekt überschritten wurde, könnte ein Dienst mit einem QuotaFailure-Detail antworten, das die Projekt-ID und die Beschreibung des überschrittenen Kontingentlimits enthält. Wenn der Dienst im aufrufenden Projekt in der Entwicklerkonsole nicht aktiviert ist, kann ein Dienst mit der Projekt-ID antworten und service_disabled auf „true“ setzen.

Weitere Informationen zur Behandlung von Kontingentfehlern finden Sie auch unter „RetryInfo“ und „Help“.

Felder
violations[]

Violation

Beschreibt alle Kontingentüberschreitungen.

Verstoß

Ein Nachrichtentyp, der zur Beschreibung eines einzelnen Kontingentverstoßes verwendet wird. Beispiel: Ein Tageskontingent oder ein benutzerdefiniertes Kontingent wurde überschritten.

Felder
subject

string

Das Subjekt, bei dem die Kontingentprüfung fehlgeschlagen ist. Beispiel: „clientip:“ oder „project:“.
description

string

Eine Beschreibung, wie die Kontingentprüfung fehlgeschlagen ist. Clients können anhand dieser Beschreibung mehr über die Kontingentkonfiguration in der öffentlichen Dokumentation des Dienstes erfahren oder das entsprechende Kontingentlimit finden, das über die Entwicklerkonsole angepasst werden soll.

Beispiel: „Service disabled“ (Dienst deaktiviert) oder „Daily Limit for read operations exceeded“ (Tägliches Limit für Lesevorgänge überschritten).
api_service

string

Der API-Dienst, aus dem QuotaFailure.Violation stammt. In einigen Fällen stammen Kontingentprobleme von einem anderen API-Dienst als dem, der aufgerufen wurde. Mit anderen Worten: Eine Abhängigkeit des aufgerufenen API-Dienstes könnte die Ursache für QuotaFailure sein. In diesem Feld würde der Name des API-Dienstes der Abhängigkeit stehen.

Wenn die aufgerufene API beispielsweise die Kubernetes Engine API (container.googleapis.com) ist und ein Kontingentverstoß in der Kubernetes Engine API selbst auftritt, wäre dieser Wert „container.googleapis.com“. Wenn der Kontingentverstoß hingegen auftritt, wenn die Kubernetes Engine API VMs in der Compute Engine API (compute.googleapis.com) erstellt, ist in diesem Feld „compute.googleapis.com“ angegeben.
quota_metric

string

Der Messwert des verletzten Kontingents. Ein Kontingentmesswert ist ein benannter Zähler zum Messen der Nutzung, z. B. API-Anfragen oder CPUs. Wenn in einem Dienst eine Aktivität stattfindet, z. B. die Zuweisung einer virtuellen Maschine, können ein oder mehrere Kontingentmesswerte betroffen sein.

Beispiele: „compute.googleapis.com/cpus_per_vm_family“, „storage.googleapis.com/internet_egress_bandwidth“.
quota_id

string

Die ID des verletzten Kontingents. Dies ist die eindeutige Kennung eines Kontingents im Kontext eines API-Dienstes. Sie wird auch als „Name des Limits“ bezeichnet.

Beispiel: „CPUS-PER-VM-FAMILY-per-project-region“.
quota_dimensions

map<string, string>

Die Dimensionen des überschrittenen Kontingents. Jedes nicht globale Kontingent wird für eine Reihe von Dimensionen durchgesetzt. Mit dem Kontingentmesswert wird definiert, was gezählt werden soll, und mit den Dimensionen wird angegeben, für welche Aspekte der Zähler erhöht werden soll.

Das Kontingent „CPUs pro Region und VM-Familie“ erzwingt beispielsweise ein Limit für den Messwert „compute.googleapis.com/cpus_per_vm_family“ für die Dimensionen „region“ und „vm_family“. Wenn der Verstoß in der Region „us-central1“ und für die VM-Familie „n1“ aufgetreten ist, wären die quota_dimensions

{ "region": "us-central1", "vm_family": "n1", }

Wenn ein Kontingent global erzwungen wird, sind die quota_dimensions immer leer.
quota_value

int64

Der erzwungene Kontingentwert zum Zeitpunkt des QuotaFailure.

Wenn der erzwungene Kontingentwert zum Zeitpunkt des QuotaFailure für die Anzahl der CPUs beispielsweise „10“ ist, spiegelt der Wert dieses Felds diese Menge wider.
future_quota_value

int64

Der neue Kontingentwert, der zum Zeitpunkt des Verstoßes eingeführt wird. Nach Abschluss des Roll-outs wird dieser Wert anstelle von „quota_value“ erzwungen. Wenn zum Zeitpunkt des Verstoßes kein Roll-out läuft, ist dieses Feld nicht festgelegt.

Wenn zum Zeitpunkt des Verstoßes beispielsweise ein Roll-out im Gange ist, bei dem das Kontingent für die Anzahl der CPUs von 10 auf 20 geändert wird, ist 20 der Wert dieses Felds.

RequestInfo

Enthält Metadaten zur Anfrage, die Clients beim Melden eines Fehlers oder bei anderen Formen von Feedback anhängen können.

Felder
request_id

string

Ein undurchsichtiger String, der nur von dem Dienst interpretiert werden sollte, der ihn generiert. Sie kann beispielsweise verwendet werden, um Anfragen in den Logs des Dienstes zu identifizieren.
serving_data

string

Alle Daten, die zur Bearbeitung dieser Anfrage verwendet wurden. Zum Beispiel ein verschlüsselter Stacktrace, der zur Fehlerbehebung an den Dienstanbieter zurückgesendet werden kann.

ResourceInfo

Beschreibt die Ressource, auf die zugegriffen wird.

Felder
resource_type

string

Ein Name für den Ressourcentyp, auf den zugegriffen wird, z.B. "sql-Tabelle", "cloud storage bucket", "file", "Google calendar"; oder die Typ-URL der Ressource: z.B. „type.googleapis.com/google.pubsub.v1.Topic“.
resource_name

string

Der Name der Ressource, auf die zugegriffen wird. Beispiel: Der Name eines freigegebenen Kalenders: „beispiel.de_4fghdhgsrgh@group.calendar.google.com“, wenn der aktuelle Fehler google.rpc.Code.PERMISSION_DENIED ist.
owner

string

Der Inhaber der Ressource (optional). Beispiel: „user:“ oder „project:“.
description

string

Beschreibt, welcher Fehler beim Zugriff auf diese Ressource aufgetreten ist. Wenn Sie beispielsweise ein Cloud-Projekt aktualisieren möchten, benötigen Sie möglicherweise die Berechtigung writer für das Entwicklerkonsolenprojekt.

RetryInfo

Beschreibt, wann Clients eine fehlgeschlagene Anfrage wiederholen können. Clients können die Empfehlung hier ignorieren oder es noch einmal versuchen, wenn diese Informationen in Fehlerantworten fehlen.

Es wird immer empfohlen, dass Clients beim Wiederholen den exponentiellen Backoff verwenden.

Clients sollten mit dem Wiederholungsversuch warten, bis retry_delay Zeit seit dem Empfang der Fehlerantwort vergangen ist. Wenn auch das Wiederholen von Anfragen fehlschlägt, sollten Clients ein exponentielles Backoff-Schema verwenden, um die Verzögerung zwischen Wiederholungen basierend auf retry_delay schrittweise zu erhöhen, bis entweder eine maximale Anzahl von Wiederholungen oder eine maximale Wiederholungsverzögerung erreicht wurde.

Felder
retry_delay

Duration

Clients sollten mindestens so lange warten, bevor sie dieselbe Anfrage noch einmal senden.

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 für Nutzer sichtbare Fehlermeldung 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.