Package google.rpc

Indeks

BadRequest

Opisuje naruszenia w żądaniu klienta. Ten typ błędu dotyczy aspektów składniowych żądania.

Pola
field_violations[]

FieldViolation

Opisuje wszystkie naruszenia w żądaniu klienta.

FieldViolation

Typ wiadomości używany do opisywania pojedynczego pola nieprawidłowego żądania.

Pola
field

string

Ścieżka prowadząca do pola w treści żądania. Wartość będzie ciągiem identyfikatorów oddzielonych kropkami, które identyfikują pole bufora protokołu.

Weź pod uwagę następujące kwestie:

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

W tym przykładzie w protokole field może przyjąć jedną z tych wartości:

  • full_name w przypadku naruszenia zasad dotyczących wartości full_name
  • email_addresses[1].email za naruszenie w polu email pierwszej wiadomości email_addresses
  • email_addresses[3].type[2] w przypadku naruszenia w drugiej type wartości w trzeciej email_addresses wiadomości.

W formacie JSON te same wartości są reprezentowane w ten sposób:

  • fullName w przypadku naruszenia zasad dotyczących wartości fullName
  • emailAddresses[1].email za naruszenie w polu email pierwszej wiadomości emailAddresses
  • emailAddresses[3].type[2] w przypadku naruszenia w drugiej type wartości w trzeciej emailAddresses wiadomości.
description

string

Opis, dlaczego element żądania jest nieprawidłowy.
reason

string

Przyczyna błędu na poziomie pola. Jest to stała wartość, która określa bezpośrednią przyczynę błędu na poziomie pola. Powinien on jednoznacznie identyfikować typ naruszenia pola w zakresie google.rpc.ErrorInfo.domain. Powinien mieć maksymalnie 63 znaki i pasować do wyrażenia regularnego [A-Z][A-Z0-9_]+[A-Z0-9], które reprezentuje format UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

Zawiera zlokalizowany komunikat o błędzie na poziomie pola, który można bezpiecznie zwrócić do klienta interfejsu API.

Kod

Kanoniczne kody błędów interfejsów API gRPC.

Czasami może obowiązywać kilka kodów błędów. Usługi powinny zwracać najbardziej szczegółowy kod błędu, który ma zastosowanie. Jeśli na przykład oba kody mają zastosowanie, preferuj OUT_OF_RANGE zamiast FAILED_PRECONDITION. Podobnie preferuj NOT_FOUND lub ALREADY_EXISTS zamiast FAILED_PRECONDITION.

Wartości w polu enum
OK

Nie jest to błąd. Zwracany w przypadku powodzenia.

Mapowanie HTTP: 200 OK
CANCELLED

Operacja została anulowana, zwykle przez element wywołujący.

Mapowanie HTTP: 499 Klient zamknął żądanie
UNKNOWN

Nieznany błąd. Na przykład ten błąd może być zwracany, gdy wartość Status otrzymana z innej przestrzeni adresowej należy do przestrzeni błędów, która nie jest znana w tej przestrzeni adresowej. Na ten błąd mogą być też konwertowane błędy zgłaszane przez interfejsy API, które nie zwracają wystarczającej ilości informacji o błędach.

Mapowanie HTTP: 500 Internal Server Error
INVALID_ARGUMENT

Klient podał nieprawidłowy argument. Pamiętaj, że różni się on od FAILED_PRECONDITION. INVALID_ARGUMENT oznacza argumenty, które są problematyczne niezależnie od stanu systemu (np. nieprawidłowa nazwa pliku).

Mapowanie HTTP: 400 Nieprawidłowe żądanie
DEADLINE_EXCEEDED

Termin upłynął przed wykonaniem operacji. W przypadku operacji, które zmieniają stan systemu, ten błąd może zostać zwrócony nawet wówczas, gdy operacja zakończyła się pomyślnie. Na przykład pomyślna odpowiedź serwera mogła być tak opóźniona, że termin upłynął.

Mapowanie HTTP: 504 Przekroczony czas bramy
NOT_FOUND

Nie znaleziono żądanego elementu (np. pliku lub katalogu).

Uwaga dla programistów serwerów: jeśli żądanie zostanie odrzucone w przypadku całej klasy użytkowników, np. w ramach stopniowego wdrażania funkcji lub nieudokumentowanej listy dozwolonych, można użyć kodu NOT_FOUND. Jeśli prośba zostanie odrzucona w przypadku niektórych użytkowników w danej klasie, np. w przypadku kontroli dostępu opartej na użytkownikach, należy użyć PERMISSION_DENIED.

Mapowanie HTTP: 404 Nie znaleziono
ALREADY_EXISTS

Encja, którą próbował utworzyć klient (np. plik lub katalog), już istnieje.

Mapowanie HTTP: 409 Konflikt
PERMISSION_DENIED

Element wywołujący nie ma uprawnień do wykonania określonej operacji. Kodu PERMISSION_DENIED nie należy używać w przypadku odrzuceń spowodowanych wyczerpaniem zasobów (w takich przypadkach użyj kodu RESOURCE_EXHAUSTED). Nie można używać kodu PERMISSION_DENIED, jeśli nie można zidentyfikować wywołującego (w przypadku tych błędów użyj kodu UNAUTHENTICATED). Ten kod błędu nie oznacza, że żądanie jest prawidłowe, a żądany podmiot istnieje lub spełnia inne warunki wstępne.

Mapowanie HTTP: 403 Dostęp zabroniony
UNAUTHENTICATED

Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji.

Mapowanie HTTP: 401 Unauthorized
RESOURCE_EXHAUSTED

Jeden z zasobów został wyczerpany, być może limit na użytkownika lub cała pamięć systemu plików.

Mapowanie HTTP: 429 Zbyt wiele żądań
FAILED_PRECONDITION

Operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do jej wykonania. Na przykład katalog do usunięcia nie jest pusty, operacja rmdir jest stosowana do elementu, który nie jest katalogiem itp.

Osoby wdrażające usługę mogą skorzystać z tych wytycznych, aby zdecydować, czy użyć FAILED_PRECONDITION, ABORTED czy UNAVAILABLE: (a) użyj UNAVAILABLE, jeśli klient może ponowić tylko połączenie, które się nie powiodło. (b) Użyj kodu ABORTED, jeśli klient powinien ponowić próbę na wyższym poziomie. Na przykład gdy testowanie i ustawianie określone przez klienta nie powiedzie się, co oznacza, że klient powinien ponownie uruchomić sekwencję odczytu, modyfikacji i zapisu. (c) Użyj FAILED_PRECONDITION, jeśli klient nie powinien ponawiać próby, dopóki stan systemu nie zostanie jawnie poprawiony. Jeśli na przykład polecenie „rmdir” zakończy się niepowodzeniem, ponieważ katalog nie jest pusty, należy zwrócić wartość FAILED_PRECONDITION, ponieważ klient nie powinien ponawiać próby, dopóki pliki nie zostaną usunięte z katalogu.

Mapowanie HTTP: 400 Nieprawidłowe żądanie
ABORTED

Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanej kontroli sekwencera lub przerwanej transakcji.

Wskazówki powyżej pomogą Ci zdecydować, czy użyć FAILED_PRECONDITION, ABORTED czy UNAVAILABLE.

Mapowanie HTTP: 409 Konflikt
OUT_OF_RANGE

Operacja została podjęta poza prawidłowym zakresem. np. próba odczytania danych po osiągnięciu końca pliku.

W przeciwieństwie do błędu INVALID_ARGUMENT ten błąd wskazuje na problem, który można rozwiązać, jeśli zmieni się stan systemu. Na przykład 32-bitowy system plików wygeneruje INVALID_ARGUMENT, jeśli zostanie poproszony o odczyt z przesunięciem, które nie mieści się w zakresie [0, 2^32-1], ale wygeneruje OUT_OF_RANGE, jeśli zostanie poproszony o odczyt z przesunięciem przekraczającym bieżący rozmiar pliku.

Między FAILED_PRECONDITION a OUT_OF_RANGE jest sporo podobieństw. Zalecamy używanie kodu OUT_OF_RANGE (bardziej szczegółowego błędu), gdy ma on zastosowanie, aby osoby wywołujące, które iterują po przestrzeni, mogły łatwo wyszukać błąd OUT_OF_RANGE i wykryć, kiedy skończą.

Mapowanie HTTP: 400 Nieprawidłowe żądanie
UNIMPLEMENTED

Operacja nie jest wdrożona lub nie jest obsługiwana/włączona w tej usłudze.

Mapowanie HTTP: 501 Nie zaimplementowano
INTERNAL

Błędy wewnętrzne. Oznacza to, że pewne niezmienniki oczekiwane przez system bazowy zostały uszkodzone. Ten kod błędu jest zarezerwowany dla poważnych błędów.

Mapowanie HTTP: 500 Internal Server Error
UNAVAILABLE

Usługa jest obecnie niedostępna. Jest to najczęściej stan przejściowy, który można rozwiązać, ponawiając próbę z wycofywaniem. Pamiętaj, że ponawianie operacji nieidempotentnych nie zawsze jest bezpieczne.

Wskazówki powyżej pomogą Ci zdecydować, czy użyć FAILED_PRECONDITION, ABORTED czy UNAVAILABLE.

Mapowanie HTTP: 503 Usługa niedostępna
DATA_LOSS

Nieodwracalna utrata lub uszkodzenie danych.

Mapowanie HTTP: 500 Internal Server Error

ErrorInfo

Opisuje przyczynę błędu ze szczegółami strukturalnymi.

Przykład błędu podczas kontaktowania się z interfejsem API „pubsub.googleapis.com”, gdy nie jest on włączony:

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

Ta odpowiedź oznacza, że interfejs pubsub.googleapis.com API nie jest włączony.

Przykład błędu zwracanego podczas próby utworzenia instancji Spannera w regionie, w którym nie ma dostępnych zasobów:

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

string

Przyczyna błędu. Jest to stała wartość, która określa bezpośrednią przyczynę błędu. Przyczyny błędów są unikalne w ramach określonej domeny błędów. Powinien mieć maksymalnie 63 znaki i pasować do wyrażenia regularnego [A-Z][A-Z0-9_]+[A-Z0-9], które reprezentuje format UPPER_SNAKE_CASE.
domain

string

Grupa logiczna, do której należy „przyczyna”. Domena błędu to zwykle zarejestrowana nazwa usługi narzędzia lub produktu, który generuje błąd. Przykład: „pubsub.googleapis.com”. Jeśli błąd jest generowany przez jakąś wspólną infrastrukturę, domena błędu musi być globalnie unikalną wartością, która identyfikuje tę infrastrukturę. W przypadku infrastruktury interfejsu API Google domena błędu to „googleapis.com”.
metadata

map<string, string>

Dodatkowe szczegóły strukturalne dotyczące tego błędu.

Klucze muszą być zgodne z wyrażeniem regularnym [a-z][a-zA-Z0-9-_]+, ale najlepiej, aby były zapisane w formacie lowerCamelCase. Maksymalna długość to 64 znaki. Podczas określania aktualnej wartości przekroczonego limitu jednostki powinny być zawarte w kluczu, a nie w wartości. Jeśli np. klient przekroczy liczbę instancji, które można utworzyć w ramach jednego żądania (pakietowego), zamiast {"instanceLimit": "100/request"} powinna zostać zwrócona wartość {"instanceLimitPerRequest": "100"}.

Pomoc

Zawiera linki do dokumentacji lub umożliwia wykonanie działania poza pasmem.

Jeśli na przykład weryfikacja limitu nie powiodła się z powodu błędu wskazującego, że projekt wywołujący nie ma włączonej usługi, do której uzyskuje dostęp, może to zawierać adres URL prowadzący bezpośrednio do odpowiedniego miejsca w konsoli dewelopera, w którym można włączyć tę usługę.

Pola

LocalizedMessage

Zawiera zlokalizowany komunikat o błędzie, który można bezpiecznie zwrócić użytkownikowi i dołączyć do błędu RPC.

Pola
locale

string

Używane ustawienia regionalne zgodnie ze specyfikacją określoną na stronie https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Przykłady: „en-US”, „fr-CH”, „es-MX”.
message

string

Zlokalizowany komunikat o błędzie w podanym języku.

PreconditionFailure

Opisuje, które warunki wstępne nie zostały spełnione.

Jeśli na przykład wywołanie RPC nie powiodło się, ponieważ wymagało potwierdzenia Warunków korzystania z usługi, w wiadomości PreconditionFailure może zostać wymienione naruszenie tych warunków.

Pola
violations[]

Violation

Opisuje wszystkie naruszenia warunków wstępnych.

Naruszenie

Typ wiadomości używany do opisywania pojedynczego błędu warunku wstępnego.

Pola
type

string

Typ błędu PreconditionFailure. Zalecamy użycie typu wyliczeniowego specyficznego dla usługi, aby zdefiniować obsługiwane podmioty naruszenia warunku wstępnego. Na przykład „TOS” w przypadku „naruszenia Warunków usługi”.
subject

string

Obiekt, którego dotyczy błąd, w odniesieniu do typu. Na przykład „google.com/cloud” w odniesieniu do typu „Warunki korzystania z usługi” wskazuje, do których warunków korzystania z usługi odnosi się informacja.
description

string

Opis tego, dlaczego warunek wstępny nie został spełniony. Deweloperzy mogą użyć tego opisu, aby dowiedzieć się, jak naprawić błąd.

Na przykład: „Nie zaakceptowano warunków usługi”.

QuotaFailure

Opisuje, dlaczego weryfikacja limitu się nie powiodła.

Jeśli na przykład w projekcie wywołującym przekroczono dzienny limit, usługa może odpowiedzieć szczegółami QuotaFailure zawierającymi identyfikator projektu i opis przekroczonego limitu. Jeśli projekt wywołujący nie włączył usługi w konsoli dewelopera, usługa może odpowiedzieć identyfikatorem projektu i ustawić wartość service_disabled na „true”.

Więcej informacji o obsłudze błędów związanych z limitami znajdziesz w sekcjach RetryInfo i Help.

Pola
violations[]

Violation

Opisuje wszystkie naruszenia limitu.

Naruszenie

Typ wiadomości używany do opisywania pojedynczego naruszenia limitu. Może to być np. przekroczony dzienny limit lub limit niestandardowy.

Pola
subject

string

Temat, w przypadku którego nie udało się sprawdzić limitu. Na przykład „clientip:” lub „project:”.
description

string

Opis nieudanego sprawdzenia limitu. Klienci mogą użyć tego opisu, aby dowiedzieć się więcej o konfiguracji limitu w publicznej dokumentacji usługi lub znaleźć odpowiedni limit, który można dostosować w konsoli dewelopera.

Na przykład „Usługa wyłączona” lub „Przekroczono dzienny limit operacji odczytu”.
api_service

string

Usługa API, z której pochodzi QuotaFailure.Violation. W niektórych przypadkach problemy z limitem wynikają z usługi API innej niż ta, która została wywołana. Innymi słowy, przyczyną błędu QuotaFailure może być zależność wywoływanej usługi API, a w tym polu będzie znajdować się nazwa usługi API, od której zależy wywoływana usługa.

Jeśli na przykład wywoływany interfejs API to Kubernetes Engine API (container.googleapis.com), a naruszenie limitu nastąpi w tym interfejsie, to pole będzie miało wartość „container.googleapis.com”. Jeśli z kolei naruszenie limitu nastąpi, gdy interfejs Kubernetes Engine API tworzy maszyny wirtualne w interfejsie Compute Engine API (compute.googleapis.com), to pole będzie miało wartość „compute.googleapis.com”.
quota_metric

string

Rodzaj danych, których dotyczy przekroczenie limitu. Dane dotyczące limitu to nazwany licznik służący do pomiaru wykorzystania, np. żądań interfejsu API lub procesorów. Gdy w usłudze wystąpi działanie, np. przydzielenie maszyny wirtualnej, może to wpłynąć na co najmniej 1 rodzaj limitu.

Na przykład „compute.googleapis.com/cpus_per_vm_family”, „storage.googleapis.com/internet_egress_bandwidth”.
quota_id

string

Identyfikator przekroczonego limitu. Jest to unikalny identyfikator limitu w kontekście usługi API.

Na przykład „CPUS-PER-VM-FAMILY-per-project-region”.
quota_dimensions

map<string, string>

Wymiary naruszonego limitu. Każdy limit nieglobalny jest egzekwowany w przypadku określonego zestawu wymiarów. Rodzaj danych limitu określa, co ma być zliczane, a wymiary określają, w przypadku jakich aspektów licznik ma być zwiększany.

Na przykład limit „Procesory na region na rodzinę maszyn wirtualnych” wymusza limit na dane „compute.googleapis.com/cpus_per_vm_family” w wymiarach „region” i „vm_family”. Jeśli naruszenie wystąpiło w regionie „us-central1” w przypadku rodziny maszyn wirtualnych „n1”, wymiary limitu to:

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

Gdy limit jest egzekwowany globalnie, pole quota_dimensions jest zawsze puste.
quota_value

int64

Wartość egzekwowanego limitu w momencie QuotaFailure.

Jeśli na przykład w momencie wystąpienia zdarzenia QuotaFailure wymuszona wartość limitu liczby procesorów wynosi „10”, wartość tego pola będzie odzwierciedlać tę ilość.
future_quota_value

int64

Nowa wartość limitu, która jest wdrażana w momencie naruszenia. Po zakończeniu procesu udostępniania ta wartość będzie obowiązywać zamiast wartości quota_value. Jeśli w momencie naruszenia zasad nie trwa żadne wdrażanie, to pole nie jest ustawione.

Jeśli np. w momencie naruszenia zasad trwa wdrażanie zmiany limitu liczby procesorów z 10 na 20, wartością tego pola będzie 20.

RequestInfo

Zawiera metadane dotyczące żądania, które klienci mogą dołączyć podczas zgłaszania błędu lub przesyłania innych form opinii.

Pola
request_id

string

Nieprzezroczysty ciąg znaków, który powinien być interpretowany tylko przez usługę, która go wygenerowała. Może on na przykład służyć do identyfikowania żądań w dziennikach usługi.
serving_data

string

Wszelkie dane użyte do obsługi tego żądania. Na przykład zaszyfrowany ślad stosu, który można odesłać do dostawcy usług w celu debugowania.

ResourceInfo

Opisuje zasób, do którego uzyskuje się dostęp.

Pola
resource_type

string

Nazwa typu zasobu, do którego uzyskano dostęp, np. „tabela SQL”, „zasobnik Cloud Storage”, „plik”, „Kalendarz Google” lub adres URL typu zasobu, np. „type.googleapis.com/google.pubsub.v1.Topic”.
resource_name

string

Nazwa zasobu, do którego uzyskano dostęp. Na przykład nazwa kalendarza udostępnionego: „example.com_4fghdhgsrgh@group.calendar.google.com”, jeśli bieżący błąd to google.rpc.Code.PERMISSION_DENIED.
owner

string

Właściciel zasobu (opcjonalnie). Na przykład „user:” lub „project:”.
description

string

Opis błędu, który wystąpił podczas uzyskiwania dostępu do tego zasobu. Na przykład aktualizacja projektu Cloud może wymagać uprawnienia writer w projekcie konsoli dewelopera.

RetryInfo

Opisuje, kiedy klienci mogą ponowić nieudane żądanie. Klienci mogą zignorować rekomendację lub ponowić próbę, gdy w odpowiedziach na błędy brakuje tych informacji.

Zawsze zalecamy, aby klienci stosowali wycofywanie wykładnicze podczas ponawiania prób.

Przed ponowną próbą wysłania żądania klienci powinni odczekać retry_delay od otrzymania odpowiedzi z błędem. Jeśli ponawianie żądań również się nie powiedzie, klienci powinni użyć schematu wykładniczego wycofywania, aby stopniowo zwiększać opóźnienie między ponownymi próbami na podstawie retry_delay, dopóki nie zostanie osiągnięta maksymalna liczba ponownych prób lub maksymalne opóźnienie ponownej próby.

Pola
retry_delay

Duration

Klienci powinni odczekać co najmniej tyle czasu, zanim ponownie spróbują wysłać to samo żądanie.

Stan

Typ Status definiuje model błędu logicznego, który jest odpowiedni dla różnych środowisk programistycznych, w tym interfejsów API typu REST i RPC. Jest używany przez gRPC. Każdy komunikat Status zawiera 3 rodzaje danych: kod błędu, komunikat o błędzie i szczegóły błędu.

Więcej informacji o tym modelu błędów i sposobie pracy z nim znajdziesz w przewodniku API Design Guide.

Pola
code

int32

Kod stanu, który powinien być wartością wyliczeniową google.rpc.Code.
message

string

Komunikat o błędzie widoczny dla programisty, który powinien być w języku angielskim. Wszelkie komunikaty o błędach dla użytkowników powinny być zlokalizowane i wysyłane w polu google.rpc.Status.details lub zlokalizowane przez klienta.
details[]

Any

Lista wiadomości zawierających szczegóły błędu. Na potrzeby interfejsów API dostępny jest wspólny zestaw typów wiadomości.