Kody odpowiedzi stanu

W odpowiedziach gRPC mogą być zwracane te kody stanu: Dotyczy to wszystkich wersji gRPC opisanych na tej stronie.

Kod Stan Uwagi
0 OK Powrót: Success
1 CANCELLED Operacja została anulowana, zwykle przez element wywołujący.
2 UNKNOWN Ten błąd może zostać zwrócony, gdy wartość Status otrzymana z innego obszaru adresów należy do obszaru błędów, który nie jest znany w tym obszarze adresów. Ten błąd może też być wynikiem błędów wywołanych przez interfejsy API, które nie zwracają wystarczającej ilości informacji o błędach.
3 INVALID_ARGUMENT Klient podał nieprawidłowy argument.
4 DEADLINE_EXCEEDED Termin upłynął przed zakończeniem 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ął.
5 NOT_FOUND Nie znaleziono żądanego elementu.
6 ALREADY_EXISTS Encja, którą próbował utworzyć klient, już istnieje.
7 PERMISSION_DENIED Element wywołujący nie ma uprawnień do wykonania określonej operacji. Nie używaj wartości PERMISSION_DENIED w przypadku odrzuceń spowodowanych wyczerpaniem zasobu. W przypadku takich błędów używaj wartości RESOURCE_EXHAUSTED. Nie używaj wartości PERMISSION_DENIED, jeśli nie można zidentyfikować dzwoniącego (w przypadku takich błędów użyj wartości UNAUTHENTICATED). Wystąpienie kodu błędu PERMISSION_DENIED nie oznacza, że żądanie jest prawidłowe, że żądany element istnieje lub że spełnia inne warunki wstępne.
8 RESOURCE_EXHAUSTED Pewien zasób został wyczerpany, np. limit dla użytkownika lub miejsce na pliki na całym systemie.
9 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 lub operacja rmdir jest stosowana do niekatalogu.
10 ABORTED Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanej kontroli sekwencera lub przerwanej transakcji.
11 OUT_OF_RANGE Operacja została przeprowadzona poza prawidłowym zakresem.
12 UNIMPLEMENTED Operacja nie jest wdrożona lub nie jest obsługiwana/włączona w tej usłudze.
13 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.
14 UNAVAILABLE Usługa jest obecnie niedostępna. Jest to prawdopodobnie stan przejściowy, który można rozwiązać, ponawiając próbę z większym odstępem.
15 DATA_LOSS Nieodwracalna utrata danych lub ich uszkodzenie.
16 UNAUTHENTICATED Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji.

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

FAILED_PRECONDITION vs. ABORTED vs. UNAVAILABLE

Oto test, który pomoże Ci wybrać między FAILED_PRECONDITION, ABORTED i UNAVAILABLE:

  • Użyj UNAVAILABLE, jeśli klient może ponownie wywołać tylko nieudane wywołanie.
  • Użyj ABORTED, jeśli klient powinien podjąć kolejną próbę na wyższym poziomie, np. gdy test i ustawienie określone przez klienta się nie powiedzie, co oznacza, że klient powinien ponownie rozpocząć sekwencję odczyt–modyfikacja–zapis.
  • Użyj wartości FAILED_PRECONDITION, jeśli klient nie powinien próbować ponownie, dopóki stan systemu nie zostanie poprawiony. Jeśli na przykład polecenie „rmdir” nie powiedzie się, ponieważ katalog nie jest pusty, najlepiej zwrócić FAILED_PRECONDITION, ponieważ klient nie powinien powtarzać próby, chyba że pliki zostaną usunięte z katalogu.

INVALID_ARGUMENT vs. FAILED_PRECONDITION vs. OUT_OF_RANGE

Oto test, który pomoże Ci wybrać między INVALID_ARGUMENT, FAILED_PRECONDITION i OUT_OF_RANGE:

  • Użyj INVALID_ARGUMENT, jeśli argumenty są problematyczne niezależnie od stanu systemu. Przykład: nieprawidłowy format adresu URL
  • Użyj OUT_OF_RANGE, jeśli wartość wykracza poza zakres z powodu stanu systemu. Na przykład data rozpoczęcia jest wcześniejsza niż start_date_restrict.
  • Użyj wartości FAILED_PRECONDITION, jeśli jest ona nieprawidłowa ze względu na stan systemu, ale nie jest wartością OUT_OF_RANGE.