Code

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

Czasami może być używanych wiele kodów błędów. Usługi powinny zwracać najbardziej konkretny kod błędu. Na przykład lepiej jest wybrać OUT_OF_RANGE zamiast FAILED_PRECONDITION, jeśli obowiązują oba kody. I podobnie jak NOT_FOUND czy ALREADY_EXISTS zamiast FAILED_PRECONDITION.

Wartości w polu enum
OK	To nie błąd. Zwrot został zrealizowany. Mapowanie HTTP: 200 OK
CANCELLED	Operacja została anulowana przez użytkownika. Mapowanie HTTP: żądanie zamknięte przez klienta 499
UNKNOWN	Nieznany błąd. Ten błąd może na przykład zostać zwrócony, 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 zostać również przekonwertowany na błędy wyświetlone za pomocą interfejsów 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. Różni się to od FAILED_PRECONDITION. INVALID_ARGUMENT wskazuje argumenty, które powodują problemy bez względu na stan systemu (np. nieprawidłową nazwę pliku). Mapowanie HTTP: nieprawidłowe żądanie 400
DEADLINE_EXCEEDED	Termin wygasł przed ukoń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ął. 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, np. stopniowego wdrażania funkcji lub listy nieudokumentowanych, można użyć NOT_FOUND. Jeśli prośba o dostęp do konta niektórych użytkowników (np. kontrola dostępu oparta na danych) zostanie odrzucona, należy użyć właściwości PERMISSION_DENIED. Mapowanie HTTP: nie znaleziono strony 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. W przypadku odrzucenia spowodowanego wyczerpaniem części zasobów nie można użyć PERMISSION_DENIED (w przypadku tych błędów użyj RESOURCE_EXHAUSTED). Nie można użyć PERMISSION_DENIED, jeśli nie można zidentyfikować wywołującego (w przypadku tych błędów użyj UNAUTHENTICATED). Ten kod błędu nie sugeruje, że żądanie jest prawidłowe, czy żądany element istnieje lub spełnia inne warunki wstępne. Mapowanie HTTP: 403 Forbidden (Zabronione)
UNAUTHENTICATED	Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji. Mapowanie HTTP: 401 Brak autoryzacji
RESOURCE_EXHAUSTED	Część zasobów się wyczerpała, może to być limit na użytkownika lub cały system plików nie ma 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, a operacja rmdir zostanie zastosowana do katalogu innego niż katalog itp. Mechanizmy wykonawcze usługi mogą wykorzystać FAILED_PRECONDITION, ABORTED i UNAVAILABLE do tego celu, aby zaimplementować usługi: (a) Użyj UNAVAILABLE, jeśli klient może ponowić próbę wywołania nieudanego wywołania. (b) Użyj ABORTED, jeśli klient powinien spróbować ponownie na wyższym poziomie. Jeśli na przykład w określonym przez klienta zestawie testów i zestawu wystąpił błąd, wskazuje to, ż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 bezpośrednio poprawiony. Jeśli na przykład zapis „rmdir” się nie powiedzie, ponieważ katalog nie jest pusty, powinien zostać zwrócony interfejs FAILED_PRECONDITION, ponieważ klient nie powinien próbować ponownie, chyba że pliki zostaną usunięte z katalogu. Mapowanie HTTP: nieprawidłowe żądanie 400
ABORTED	Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku niepowodzenia sekwencera lub transakcji. Zapoznaj się z podanymi wyżej wskazówkami, aby wybrać między FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: konflikt 409
OUT_OF_RANGE	Podjęto próbę wykonania operacji poza prawidłowym zakresem. Np. przeszukiwanie lub czytanie po końcu pliku. W przeciwieństwie do 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 odczytany tekst z przesunięciem przekraczającym bieżący rozmiar pliku. W pewnym stopniu pokrywają się one między FAILED_PRECONDITION a OUT_OF_RANGE. Jeśli występuje błąd OUT_OF_RANGE, zalecamy użycie go (bardziej szczegółowych błędów), aby osoby wywołujące iterację mogły z łatwością wykrywać błąd OUT_OF_RANGE w pokoju. Mapowanie HTTP: nieprawidłowe żądanie 400
UNIMPLEMENTED	Operacja nie jest wdrożona lub nie jest obsługiwana/włączona 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ć przez ponowienie próby. Pamiętaj, że nie zawsze można spróbować ponownie wykonać operacje pozbawione identyfikatora. Zapoznaj się z podanymi wyżej wskazówkami, aby wybrać między FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: usługa 503 niedostępna
DATA_LOSS	Nieodwracalna utrata danych lub ich uszkodzenie. Mapowanie HTTP: wewnętrzny błąd serwera 500