Code

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

Czasami może pojawić się kilka kodów błędów. Usługi powinny zwracać najbardziej szczegółowy kod błędu, który ma zastosowanie. Na przykład w przypadku obu kodów preferuj OUT_OF_RANGE, a nie FAILED_PRECONDITION. Podobnie wolą opcję NOT_FOUND lub ALREADY_EXISTS zamiast FAILED_PRECONDITION.

Wartości w polu enum
OK	To nie jest błąd. zwracanych w przypadku sukcesu. Mapowanie HTTP: 200 OK
CANCELLED	Operacja została anulowana, zwykle przez osobę wywołującą. Mapowanie HTTP: żądanie zamknięcia klienta 499
UNKNOWN	Nieznany błąd. Ten błąd może być zwracany na przykład wtedy, gdy wartość Status otrzymana z innej przestrzeni adresowej należy do przestrzeni błędów, która nie jest znana w tej przestrzeni adresowej. Ten błąd mogą również zostać przekonwertowane przez błędy zgłoszone 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ę to od FAILED_PRECONDITION. INVALID_ARGUMENT wskazuje argumenty, które powodują problemy niezależnie od stanu systemu (np. nieprawidłowo sformatowana nazwa pliku). Mapowanie HTTP: nieprawidłowe żądanie 400
DEADLINE_EXCEEDED	Termin minął przed ukończeniem operacji. W przypadku operacji, które zmieniają stan systemu, ten błąd może zostać zwrócony nawet wtedy, 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 udało się znaleźć żądanej jednostki (np. pliku lub katalogu). Uwaga dla programistów serwerów: jeśli żądanie zostanie odrzucone w przypadku całej klasy użytkowników (np. stopniowe wdrażanie funkcji lub nieudokumentowana lista dozwolonych), może zostać użyta NOT_FOUND. W przypadku odrzucenia prośby w przypadku niektórych użytkowników w klasie użytkowników (na przykład przy użyciu kontroli dostępu opartej na użytkownikach) trzeba użyć funkcji PERMISSION_DENIED. Mapowanie HTTP: Nie znaleziono błędu 404
ALREADY_EXISTS	Encja, którą klient próbował utworzyć (np. plik lub katalog), już istnieje. Mapowanie HTTP: konflikt 409
PERMISSION_DENIED	Wywołujący nie ma uprawnień do wykonania określonej operacji. Parametru PERMISSION_DENIED nie można używać w przypadku odrzuceń spowodowanych wyczerpaniem się zasobów (w przypadku takich błędów użyj zasady RESOURCE_EXHAUSTED). Jeśli nie można zidentyfikować wywołującego, nie można używać metody PERMISSION_DENIED (w przypadku takich błędów użyj metody UNAUTHENTICATED). Ten kod błędu nie oznacza, że żądanie jest prawidłowe, ten podmiot istnieje lub spełnia inne warunki wstępne. Mapowanie HTTP: kod 403 (Zabroniony)
UNAUTHENTICATED	Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji. Mapowanie HTTP: błąd 401 (Brak autoryzacji)
RESOURCE_EXHAUSTED	Część zasobów została wyczerpana, na przykład limit na użytkownika lub w całym systemie plików brakuje 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 została zastosowana do elementu innego niż katalog itd. Implementatory usług mogą wybierać między FAILED_PRECONDITION, ABORTED a UNAVAILABLE na podstawie tych wytycznych: (a) Użyj właściwości UNAVAILABLE, jeśli klient może ponowić próbę tylko nieudanego wywołania. (b) Użyj ABORTED, jeśli klient powinien spróbować ponownie na wyższym poziomie. Na przykład gdy określony przez klienta parametr test i ustawiony nie powiedzie się, wskazując, że klient powinien ponownie uruchomić sekwencję odczytu, modyfikacji i zapisu. (c) Użyj reguły FAILED_PRECONDITION, jeśli klient nie powinien ponawiać próby, dopóki stan systemu nie zostanie bezpośrednio poprawiony. Na przykład, jeśli wartość „rmdir” kończy się niepowodzeniem, ponieważ katalog nie jest pusty, dlatego powinien zostać zwrócony kod FAILED_PRECONDITION, ponieważ klient nie powinien ponawiać próby, chyba że pliki zostaną usunięte z katalogu. Mapowanie HTTP: nieprawidłowe żądanie 400
ABORTED	Operacja została przerwana, zwykle z powodu problemu równoczesności, takiego jak błąd kontroli sekwencera lub przerwanie transakcji. Zapoznaj się z powyższymi wskazówkami, aby wybrać tę opcję: FAILED_PRECONDITION, ABORTED lub UNAVAILABLE. Mapowanie HTTP: konflikt 409
OUT_OF_RANGE	Podjęto próbę wykonania operacji poza prawidłowym zakresem. Może to być np. przewinięcie do końca pliku lub odczyt. W przeciwieństwie do zasady INVALID_ARGUMENT ten błąd oznacza problem, który można rozwiązać, jeśli zmieni się stan systemu. Na przykład 32-bitowy system plików wygeneruje żądanie INVALID_ARGUMENT, jeśli zostanie wyświetlone żądanie odczytu z przesunięciem spoza zakresu [0,2^32-1]. Jeśli jednak poprosi o odczyt z przesunięcia względem bieżącego rozmiaru pliku, wygeneruje wartość OUT_OF_RANGE. Zakres dat FAILED_PRECONDITION i OUT_OF_RANGE w dużym stopniu się pokrywa. W razie potrzeby zalecamy użycie OUT_OF_RANGE (bardziej szczegółowego błędu), aby osoby dzwoniące wykonujące iteracje w pokoju mogły łatwo wyszukać błąd OUT_OF_RANGE, który pozwoli wykryć, że zadanie zostało wykonane. Mapowanie HTTP: nieprawidłowe żądanie 400
UNIMPLEMENTED	Ta operacja nie została wdrożona albo nie jest obsługiwana lub włączona w tej usłudze. Mapowanie HTTP: kod 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: wewnętrzny błąd serwera 500
UNAVAILABLE	Usługa jest obecnie niedostępna. Najprawdopodobniej jest to stan przejściowy, który można rozwiązać, ponawiając próbę z ponownym opóźnieniem. Pamiętaj, że ponawianie operacji nieidempotentnych nie zawsze jest bezpieczne. Zapoznaj się z powyższymi wskazówkami, aby wybrać między FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: Usługa niedostępna 503
DATA_LOSS	Nieodwracalna utrata lub uszkodzenie danych. Mapowanie HTTP: wewnętrzny błąd serwera 500