Package google.rpc

Indeks

Kod

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

Czasami może być kilka kodów błędów. Usługi powinny zwracać najbardziej szczegółowy kod błędu. Jeśli oba kody są odpowiednie, preferuj kod OUT_OF_RANGE zamiast FAILED_PRECONDITION. Podobnie preferuj NOT_FOUND lub ALREADY_EXISTS zamiast FAILED_PRECONDITION.

Wartości w polu enum
OK

Nie jest błędem; zwracany po zakończeniu operacji.

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. Ten błąd może zostać zwrócony, gdy wartość Status otrzymana z innej przestrzeni adresów należy do przestrzeni błędów, która nie jest znana w tej przestrzeni adresów. Ten błąd może też oznaczać błędy zgłoszone przez interfejsy API, które nie zwracają wystarczającej ilości informacji o błędach.

Mapowanie HTTP: 500 Wewnętrzny błąd serwera
INVALID_ARGUMENT

Klient podał nieprawidłowy argument. Uwaga: to nie to samo co FAILED_PRECONDITION. INVALID_ARGUMENT oznacza argumenty, które są problematyczne niezależnie od stanu systemu (np. źle sformatowana 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: przekroczenie limitu czasu bramy (504)
NOT_FOUND

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

Uwaga dla programistów serwerów: jeśli prośba zostanie odrzucona dla całej klasy użytkowników, np. w przypadku stopniowego wdrażania funkcji lub nieudokumentowanej listy dozwolonych, można użyć NOT_FOUND. Jeśli prośba zostanie odrzucona w przypadku niektórych użytkowników w danej klasie użytkowników, 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: konflikt 409
PERMISSION_DENIED

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

Mapowanie HTTP: 403 Zabronione
UNAUTHENTICATED

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

Mapowanie HTTP: 401 Nieautoryzowany
RESOURCE_EXHAUSTED

Pewien zasób został wyczerpany, np. limit dla użytkownika lub miejsce na pliki na całym systemie.

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, który ma zostać usunięty, nie jest pusty, operacja rmdir jest stosowana do niekatalogu itp.

Implementatorzy usługi mogą skorzystać z tych wskazówek, aby wybrać FAILED_PRECONDITION, ABORTED lub UNAVAILABLE: (a) Użyj UNAVAILABLE, jeśli klient może ponownie wykonać tylko nieudane wywołanie. (b) Użyj wartości ABORTED, jeśli klient powinien podjąć kolejną próbę na wyższym poziomie. Na przykład, gdy test i ustawienie określone przez klienta się nie powiedzie, co oznacza, że klient powinien ponownie uruchomić sekwencję odczyt-modyfikacja-zapis. (c) Użyj FAILED_PRECONDITION, jeśli klient nie powinien próbować ponownie, dopóki stan systemu nie zostanie bezpośrednio poprawiony. Jeśli na przykład polecenie „rmdir” zakończy się niepowodzeniem, ponieważ katalog nie jest pusty, powinna zostać zwrócona wartość FAILED_PRECONDITION, ponieważ klient nie powinien powtarzać próby, chyba że pliki 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.

Aby zdecydować, czy użyć FAILED_PRECONDITION, ABORTED czy UNAVAILABLE, zapoznaj się z wytycznymi powyżej.

Mapowanie HTTP: konflikt 409
OUT_OF_RANGE

Operacja została podjęta poza prawidłowym zakresem. Przykład: przeskakiwanie do początku lub koniec pliku.

W przeciwieństwie do błędu INVALID_ARGUMENT ten błąd wskazuje problem, który można rozwiązać, zmieniając stan systemu. Na przykład system plików 32-bitowych zwróci wartość INVALID_ARGUMENT, jeśli poprosisz o odczyt z odstępem, który nie mieści się w zakresie [0, 2^32-1], ale zwróci wartość OUT_OF_RANGE, jeśli poprosisz o odczyt z odstępem poza bieżący rozmiar pliku.

Wartości FAILED_PRECONDITION i OUT_OF_RANGE nakładają się na siebie. Zalecamy użycie OUT_OF_RANGE (błędu bardziej szczegółowego), aby osoby wywołujące, które przechodzą przez przestrzeń, mogły łatwo znaleźć błąd OUT_OF_RANGE, który można wykryć po zakończeniu.

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 Wewnętrzny błąd serwera
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 większym odstępem. Pamiętaj, że ponowne próby wykonywania operacji nie idempotentnych nie zawsze są bezpieczne.

Aby zdecydować, czy użyć FAILED_PRECONDITION, ABORTED czy UNAVAILABLE, zapoznaj się z wytycznymi powyżej.

Mapowanie HTTP: 503 Usługa niedostępna
DATA_LOSS

Nieodwracalna utrata danych lub ich uszkodzenie.

Mapowanie HTTP: 500 Wewnętrzny błąd serwera

Stan

Typ Status definiuje model błędu logicznego, który jest odpowiedni w różnych środowiskach programowania, w tym w interfejsach API typu REST i RPC. Jest używany przez gRPC. Każda wiadomość Status zawiera 3 elementy danych: kod błędu, komunikat o błędzie i szczegóły błędu.

Więcej informacji o tym modelu błędów i o tym, jak z niego korzystać, znajdziesz w przewodniku API Design Guide (w języku angielskim).

Pola
code

int32

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

string

Komunikat o błędzie dla programistów, który powinien być w języku angielskim. Wszelkie komunikaty o błędach wyświetlane użytkownikowi 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. Interfejsy API mogą korzystać z wspólnego zestawu typów wiadomości.