Code

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

Czasami obowiązuje kilka kodów błędów. Usługi powinny zwracać najbardziej dokładny kod błędu. Na przykład, jeśli mają zastosowanie oba kody, preferuj ustawienie OUT_OF_RANGE zamiast FAILED_PRECONDITION. I podobnie, lepiej jest wybrać NOT_FOUND lub ALREADY_EXISTS zamiast FAILED_PRECONDITION.

Wartości w polu enum
OK	To nie błąd, a powodzenie zostało zwrócone. Mapowanie HTTP: 200
CANCELLED	Operacja została anulowana, zwykle przez rozmówcę. Mapowanie HTTP: żądanie zamknięte przez klienta: 499
UNKNOWN	Nieznany błąd. Ten błąd może być na przykład zwracany, gdy wartość Status otrzymana z innej przestrzeni adresowej należy do przestrzeni błędu, która nie jest znana w tej przestrzeni adresowej. Ten błąd może również zostać przekonwertowany na błędy przesłane przez interfejsy API, które nie zwracają wystarczającej ilości informacji o błędzie. Mapowanie HTTP: wewnętrzny błąd serwera 500
INVALID_ARGUMENT	Klient podał nieprawidłowy argument. Pamiętaj, że różni się ona od tego w polu FAILED_PRECONDITION. INVALID_ARGUMENT wskazuje argumenty, które powodują problemy niezależnie od stanu 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: czas oczekiwania bramy 504
NOT_FOUND	Nie znaleziono żądanego elementu (np. pliku lub katalogu). Uwaga do programistów serwerów: jeśli żądanie zostanie odrzucone dla całej klasy użytkowników, np. stopniowego wdrażania funkcji lub nieudokumentowanej listy dozwolonych aplikacji, może być używana wartość NOT_FOUND. Jeśli prośba została odrzucona u niektórych użytkowników należących do grupy użytkowników, na przykład na podstawie kontroli dostępu opartej na użytkownikach, należy użyć metody PERMISSION_DENIED. Mapowanie HTTP: 404 – nie znaleziono
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. W przypadku odrzuceń spowodowanych przez wyczerpanie się niektórych zasobów nie można używać PERMISSION_DENIED (zamiast tych błędów użyj RESOURCE_EXHAUSTED). Nie można użyć PERMISSION_DENIED, jeśli nie można zidentyfikować dzwoniącego (w przypadku tych błędów użyj UNAUTHENTICATED). Ten kod błędu nie wskazuje, że żądanie jest prawidłowe lub że żądany element istnieje lub 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 Brak autoryzacji
RESOURCE_EXHAUSTED	Jeden zasób mógł zostać wyczerpany, być może limit na użytkownika albo cały system plików nie mają już 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 danych spoza katalogu itp. Implementatorzy usług mogą skorzystać z tych wytycznych, aby zdecydować między FAILED_PRECONDITION, ABORTED i UNAVAILABLE: (a) użyć UNAVAILABLE, jeśli klient może spróbować ponownie nawiązać niepowodzenie. (b) Użyj ABORTED, jeśli klient powinien spróbować ponownie na wyższym poziomie. Jeśli na przykład nie uda się przeprowadzić testu i ustawienia zestawu określonego przez klienta, co będzie oznaczać, że klient powinien ponownie uruchomić sekwencję odczytu i zapisu. (c) Użyj FAILED_PRECONDITION, jeśli klient nie powinien ponawiać próby, dopóki stan systemu nie zostanie bezpośrednio poprawiony. Na przykład jeśli & "rmdir" kończy się niepowodzeniem, bo katalog nie jest pusty, powinien zostać zwrócony kod FAILED_PRECONDITION, ponieważ klient nie powinien ponawiać próby, chyba że pliki zostały usunięte z katalogu. Mapowanie HTTP: błąd 400
ABORTED	Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku niepowodzenia sekwencera lub przerwania transakcji. Zobacz wskazówki powyżej, które pomogą Ci wybrać od FAILED_PRECONDITION do ABORTED lub UNAVAILABLE. Mapowanie HTTP: konflikt 409
OUT_OF_RANGE	Podjęto próbę zakończenia prawidłowego zakresu. Może to być na przykład wyszukanie lub przeczytanie końca pliku. W przeciwieństwie do wartości INVALID_ARGUMENT ten błąd wskazuje problem, który można naprawić, gdy zmieni się stan systemu. Na przykład 32-bitowy system plików wygeneruje INVALID_ARGUMENT, jeśli zostanie poproszony o odczytanie przesunięcia, które nie mieści się w zakresie [0,2^32-1], ale wygeneruje OUT_OF_RANGE, jeśli zostanie odczytane z przesunięcia względem bieżącego rozmiaru pliku. Między FAILED_PRECONDITION a OUT_OF_RANGE pokrywa się częściowo. Zalecamy stosowanie OUT_OF_RANGE (bardziej precyzyjnego błędu), gdy ma zastosowanie, aby rozmówcy, którzy iterują przez pokój, mogli łatwo znaleźć błąd OUT_OF_RANGE w celu jego określenia. Mapowanie HTTP: błąd 400
UNIMPLEMENTED	Operacja nie została wdrożona lub nie jest obsługiwana w tej usłudze. Mapowanie HTTP: błąd 501
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ę ponowienia. Pamiętaj, że nie zawsze jest ponowne próby wykonania działań niezwiązanych z tożsamością. Zobacz wskazówki powyżej, które pomogą Ci wybrać od FAILED_PRECONDITION do ABORTED lub UNAVAILABLE. Mapowanie HTTP: usługa 503 niedostępna
DATA_LOSS	nieodwracalna utrata danych lub uszkodzenie ich; Mapowanie HTTP: wewnętrzny błąd serwera 500