Code

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

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

Wartości w polu enum
OK	To nie błąd; powodzenie zostało zwrócone. Mapowanie HTTP: 200 OK
CANCELLED	Operacja została anulowana przez operatora. Mapowanie HTTP: żądanie zamknięte przez klienta 499
UNKNOWN	Nieznany błąd. Ten błąd może się np. pojawić, gdy wartość Status otrzymana z innej przestrzeni adresowej należy do obszaru błędu, który nie jest znany w tym miejscu. Ten błąd mogą zostać również przekonwertowane na błędy zgłoszone przez interfejsy API, które nie zwracają wystarczającej ilości informacji o błędach. Mapowanie HTTP: wewnętrzny błąd serwera 500
INVALID_ARGUMENT	Klient podał nieprawidłowy argument. Różni się to od FAILED_PRECONDITION. INVALID_ARGUMENT wskazuje argumenty, które stanowią problem bez względu na stan systemu (np. nieprawidłową nazwę pliku). Mapowanie HTTP: błąd 400
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 żądanie zostanie odrzucone dla całej klasy użytkowników, na przykład stopniowego wdrażania funkcji lub listy dokumentów nieudokumentowanych, można użyć NOT_FOUND. Jeśli prośba zostanie odrzucona w przypadku niektórych użytkowników należących do klasy, np. kontroli dostępu opartej na użytkownikach, należy użyć właściwości PERMISSION_DENIED. Mapowanie HTTP: nie znaleziono 404
ALREADY_EXISTS	Element, który klient próbował utworzyć (np. plik lub katalog), już istnieje. Mapowanie HTTP: konflikt 409
PERMISSION_DENIED	Element wywołujący nie ma uprawnień do wykonania określonej operacji. PERMISSION_DENIED nie może być używane w przypadku odrzucenia z powodu wyczerpania zasobów (zamiast tego użyj RESOURCE_EXHAUSTED). Jeśli wywołania nie można zidentyfikować, nie można użyć metody PERMISSION_DENIED (zamiast tych błędów użyj UNAUTHENTICATED). Ten kod błędu nie sugeruje, że żądanie jest prawidłowe, czy żądany element istnieje albo spełnia inne warunki wstępne. Mapowanie HTTP: 403 Zabronione
UNAUTHENTICATED	Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji. Mapowanie HTTP: błąd 401
RESOURCE_EXHAUSTED	Jeden zasób został wyczerpany – być może limit na użytkownika lub cały system plików zabrakło miejsca. 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 zostanie zastosowana do katalogu itp. Decydując się na usługę FAILED_PRECONDITION, ABORTED lub UNAVAILABLE, usługi implementujące usługi mogą stosować te wskazówki: (a) użyć polecenia UNAVAILABLE, jeśli klient może spróbować ponownie nawiązać wywołanie nieudane. (b) Wybierz opcję ABORTED, jeśli klient powinien spróbować ponownie na wyższym poziomie. Jeśli na przykład określony przez klienta zestaw testów i zestawu kończy się niepowodzeniem, wskazuje to, że powinien on ponownie uruchomić sekwencję modyfikacji do odczytu i zapisu. (c) Użyj polecenia FAILED_PRECONDITION, jeśli klient nie powinien ponawiać próby, dopóki stan systemu nie zostanie bezpośrednio poprawiony. Jeśli na przykład błąd „rmdir” nie powiedzie się, ponieważ katalog nie jest pusty, należy zwrócić FAILED_PRECONDITION, ponieważ klient nie powinien próbować ponownie, chyba że pliki zostaną usunięte z katalogu. Mapowanie HTTP: błąd 400
ABORTED	Operacja została przerwana, zwykle z powodu problemu równoczesności, np. w wyniku kontroli sekwencera lub przerwania transakcji. Powyższe wytyczne ułatwią Ci wybór pomiędzy FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: konflikt 409
OUT_OF_RANGE	Podjęto próbę wykonania operacji poza prawidłowym zakresem. Przykładem może być przeszukiwanie na końcu pliku lub odczyt go. W przeciwieństwie do INVALID_ARGUMENT ten błąd wskazuje 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 wyświetlony komunikat o przesunięciu nieuwzględnionym w zakresie [0,2^32-1], ale o liczbie OUT_OF_RANGE. W pewnym stopniu pokrywają się między FAILED_PRECONDITION a OUT_OF_RANGE. Zalecamy stosowanie OUT_OF_RANGE (bardziej konkretnego błędu) podczas jego stosowania, aby osoby dzwoniące podczas powtarzania pokoju mogły z łatwością wyszukiwać błąd OUT_OF_RANGE i ustalać, kiedy niego nie ma. Mapowanie HTTP: błąd 400
UNIMPLEMENTED	Operacja nie została zaimplementowana w usłudze lub nie jest obsługiwana. Mapowanie HTTP: błąd 501 nie został zaimplementowany
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: wewnętrzny błąd serwera 500
UNAVAILABLE	Usługa jest obecnie niedostępna. Jest to najczęściej stan przejściowy, który można rozwiązać, ponawiając próbę. Pamiętaj, że nie zawsze można ponawiać próby niezwiązane z identyfikacją. Powyższe wytyczne ułatwią Ci wybór pomiędzy FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: usługa 503 niedostępna
DATA_LOSS	Nieodwracalna utrata danych lub uszkodzenie. Mapowanie HTTP: wewnętrzny błąd serwera 500