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.

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

Nieprzejrzysty ciąg znaków, który powinien być interpretowany tylko przez usługę, która go generuje. 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.

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.