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