Code
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Kanoniczne kody błędów interfejsów API gRPC.
Czasami może obowiązywać wiele kodów błędów. Usługi powinny zwracać najbardziej szczegółowy kod błędu. Na przykład: OUT_OF_RANGE zamiast FAILED_PRECONDITION, jeśli oba kody są stosowane. Podobnie preferuj NOT_FOUND lub ALREADY_EXISTS zamiast FAILED_PRECONDITION.
| Wartości w polu enum |
OK |
To nie błąd; powodzenie zostało zwrócone. Mapowanie HTTP: 200 OK |
CANCELLED |
Operacja została anulowana przez operatora. Mapowanie HTTP: żądanie zamknięte przez klienta 499 |
UNKNOWN |
Nieznany błąd. Ten błąd może się np. pojawić, gdy wartość Status otrzymana z innej przestrzeni adresowej należy do obszaru błędu, który nie jest znany w tym miejscu. Ten błąd mogą zostać również przekonwertowane na błędy zgłoszone przez interfejsy API, które nie zwracają wystarczającej ilości informacji o błędach. 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 stanowią problem bez względu na stan 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: 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, na przykład stopniowego wdrażania funkcji lub listy dokumentów nieudokumentowanych, można użyć NOT_FOUND. Jeśli prośba zostanie odrzucona w przypadku niektórych użytkowników należących do klasy, np. kontroli dostępu opartej na użytkownikach, należy użyć właściwości PERMISSION_DENIED. Mapowanie HTTP: nie znaleziono 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. PERMISSION_DENIED nie może być używane w przypadku odrzucenia z powodu wyczerpania zasobów (zamiast tego użyj RESOURCE_EXHAUSTED). Jeśli wywołania nie można zidentyfikować, nie można użyć metody PERMISSION_DENIED (zamiast tych błędów użyj UNAUTHENTICATED). Ten kod błędu nie sugeruje, że żądanie jest prawidłowe, czy żądany element istnieje albo spełnia inne warunki wstępne. Mapowanie HTTP: 403 Zabronione |
UNAUTHENTICATED |
Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji. Mapowanie HTTP: błąd 401 |
RESOURCE_EXHAUSTED |
Jeden zasób został wyczerpany – być może limit na użytkownika lub cały system plików zabrakło 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 katalogu itp. Decydując się na usługę FAILED_PRECONDITION, ABORTED lub UNAVAILABLE, usługi implementujące usługi mogą stosować te wskazówki: (a) użyć polecenia UNAVAILABLE, jeśli klient może spróbować ponownie nawiązać wywołanie nieudane. (b) Wybierz opcję ABORTED, jeśli klient powinien spróbować ponownie na wyższym poziomie. Jeśli na przykład określony przez klienta zestaw testów i zestawu kończy się niepowodzeniem, wskazuje to, że powinien on ponownie uruchomić sekwencję modyfikacji do odczytu i zapisu. (c) Użyj polecenia FAILED_PRECONDITION, jeśli klient nie powinien ponawiać próby, dopóki stan systemu nie zostanie bezpośrednio poprawiony. Jeśli na przykład błąd „rmdir” nie powiedzie się, ponieważ katalog nie jest pusty, należy zwrócić FAILED_PRECONDITION, ponieważ klient nie powinien próbować ponownie, chyba że pliki zostaną usunięte z katalogu. Mapowanie HTTP: błąd 400 |
ABORTED |
Operacja została przerwana, zwykle z powodu problemu równoczesności, np. w wyniku kontroli sekwencera lub przerwania transakcji. Powyższe wytyczne ułatwią Ci wybór pomiędzy FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: konflikt 409 |
OUT_OF_RANGE |
Podjęto próbę wykonania operacji poza prawidłowym zakresem. Przykładem może być przeszukiwanie na końcu pliku lub odczyt go. W przeciwieństwie do INVALID_ARGUMENT ten błąd wskazuje 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 wyświetlony komunikat o przesunięciu nieuwzględnionym w zakresie [0,2^32-1], ale o liczbie OUT_OF_RANGE. W pewnym stopniu pokrywają się między FAILED_PRECONDITION a OUT_OF_RANGE. Zalecamy stosowanie OUT_OF_RANGE (bardziej konkretnego błędu) podczas jego stosowania, aby osoby dzwoniące podczas powtarzania pokoju mogły z łatwością wyszukiwać błąd OUT_OF_RANGE i ustalać, kiedy niego nie ma. Mapowanie HTTP: błąd 400 |
UNIMPLEMENTED |
Operacja nie została zaimplementowana w usłudze lub nie jest obsługiwana. Mapowanie HTTP: błąd 501 nie został zaimplementowany |
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ę. Pamiętaj, że nie zawsze można ponawiać próby niezwiązane z identyfikacją. Powyższe wytyczne ułatwią Ci wybór pomiędzy FAILED_PRECONDITION, ABORTED i UNAVAILABLE. Mapowanie HTTP: usługa 503 niedostępna |
DATA_LOSS |
Nieodwracalna utrata danych lub uszkodzenie. Mapowanie HTTP: wewnętrzny błąd serwera 500 |
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-07-25 UTC.
[null,null,["Ostatnia aktualizacja: 2025-07-25 UTC."],[[["\u003cp\u003eThis documentation outlines the canonical error codes for gRPC APIs, providing a standardized way to handle and interpret errors across different services.\u003c/p\u003e\n"],["\u003cp\u003eEach error code has a specific meaning and an associated HTTP mapping for easier integration with existing web infrastructure.\u003c/p\u003e\n"],["\u003cp\u003eServices should prioritize returning the most specific error code applicable to a given situation, aiding in accurate diagnosis and troubleshooting.\u003c/p\u003e\n"],["\u003cp\u003eThe error codes cover a wide range of scenarios, including client errors, server errors, and resource constraints, ensuring comprehensive error handling.\u003c/p\u003e\n"],["\u003cp\u003eWhile some errors may be transient and recoverable through retries, others indicate more serious issues requiring system-level intervention.\u003c/p\u003e\n"]]],["gRPC APIs use specific error codes to indicate the outcome of operations. Services should return the most relevant code when multiple codes apply. Codes include `OK` for success and various error types like `CANCELLED`, `UNKNOWN`, `INVALID_ARGUMENT`, `NOT_FOUND`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, and `UNAVAILABLE`. Others, such as `FAILED_PRECONDITION`, `ABORTED`, and `OUT_OF_RANGE` are used for state-related issues. Each code also has a corresponding HTTP mapping for error communication.\n"],null,[]]
