Code

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