Code

Канонические коды ошибок для API gRPC.

Иногда могут применяться несколько кодов ошибок. Службы должны возвращать наиболее конкретный код ошибки, который применим. Например, отдайте предпочтение OUT_OF_RANGE вместо FAILED_PRECONDITION , если применимы оба кода. Аналогичным образом отдайте предпочтение NOT_FOUND или ALREADY_EXISTS вместо FAILED_PRECONDITION .

Перечисления
OK

Это не ошибка; вернулся с успехом.

HTTP-сопоставление: 200 ОК

CANCELLED

Операция была отменена, как правило, вызывающей стороной.

HTTP-сопоставление: закрытый запрос клиента 499

UNKNOWN

Неизвестная ошибка. Например, эта ошибка может быть возвращена, когда значение Status , полученное из другого адресного пространства, принадлежит пространству ошибок, которое неизвестно в этом адресном пространстве. Также в эту ошибку могут быть преобразованы ошибки, возникающие из-за API, которые не возвращают достаточно информации об ошибках.

HTTP-сопоставление: 500 внутренняя ошибка сервера

INVALID_ARGUMENT

Клиент указал недопустимый аргумент. Обратите внимание, что это отличается от FAILED_PRECONDITION . INVALID_ARGUMENT указывает на аргументы, которые являются проблемными независимо от состояния системы (например, неправильное имя файла).

HTTP-сопоставление: 400 неверных запросов

DEADLINE_EXCEEDED

Срок истек до завершения операции. Для операций, изменяющих состояние системы, эта ошибка может возвращаться, даже если операция завершилась успешно. Например, успешный ответ от сервера мог быть отложен на время, достаточное для истечения крайнего срока.

HTTP-сопоставление: тайм-аут шлюза 504

NOT_FOUND

Некоторый запрошенный объект (например, файл или каталог) не найден.

Примечание для разработчиков серверов: если запрос отклонен для всего класса пользователей, например, при постепенном развертывании функции или недокументированном списке разрешенных, можно использовать NOT_FOUND . Если запрос отклонен для некоторых пользователей в классе пользователей, например, при управлении доступом на основе пользователей, необходимо использовать PERMISSION_DENIED .

HTTP-сопоставление: 404 не найден

ALREADY_EXISTS

Объект, который клиент пытался создать (например, файл или каталог), уже существует.

HTTP-сопоставление: конфликт 409

PERMISSION_DENIED

У вызывающего объекта нет разрешения на выполнение указанной операции. PERMISSION_DENIED нельзя использовать для отклонений, вызванных исчерпанием какого-либо ресурса (вместо этого используйте RESOURCE_EXHAUSTED для таких ошибок). PERMISSION_DENIED не следует использовать, если вызывающий абонент не может быть идентифицирован (вместо этого используйте UNAUTHENTICATED для таких ошибок). Этот код ошибки не означает, что запрос действителен, или запрошенный объект существует или удовлетворяет другим предварительным условиям.

HTTP-сопоставление: 403 запрещено

UNAUTHENTICATED

В запросе нет действительных учетных данных аутентификации для операции.

HTTP-сопоставление: 401 Неавторизованный

RESOURCE_EXHAUSTED

Какой-то ресурс исчерпан, возможно, квота на пользователя или, возможно, во всей файловой системе недостаточно места.

HTTP-сопоставление: 429 слишком много запросов

FAILED_PRECONDITION

Операция отклонена, поскольку система не находится в состоянии, необходимом для выполнения операции. Например, удаляемый каталог не пуст, операция rmdir применяется к некаталогу и т. д.

Разработчики службы могут использовать следующие рекомендации для выбора между FAILED_PRECONDITION , ABORTED и UNAVAILABLE : (a) Используйте UNAVAILABLE если клиент может повторить только неудачный вызов. (b) Используйте ABORTED если клиент должен повторить попытку на более высоком уровне. Например, когда указанная клиентом проверка и установка завершается неудачей, это указывает на то, что клиент должен перезапустить последовательность чтения-изменения-записи. (c) Используйте FAILED_PRECONDITION если клиент не должен повторять попытку до тех пор, пока состояние системы не будет явно исправлено. Например, если «rmdir» завершается неудачно, потому что каталог непустой, должно быть возвращено FAILED_PRECONDITION , поскольку клиент не должен повторять попытку, пока файлы не будут удалены из каталога.

HTTP-сопоставление: 400 неверных запросов

ABORTED

Операция была прервана, как правило, из-за проблемы параллелизма, такой как сбой проверки секвенсора или прерывание транзакции.

См. приведенные выше рекомендации по выбору между FAILED_PRECONDITION , ABORTED и UNAVAILABLE .

HTTP-сопоставление: конфликт 409

OUT_OF_RANGE

Была предпринята попытка выполнить операцию за пределами допустимого диапазона. Например, поиск или чтение конца файла.

В отличие от INVALID_ARGUMENT , эта ошибка указывает на проблему, которую можно устранить, если изменится состояние системы. Например, 32-битная файловая система сгенерирует INVALID_ARGUMENT если ее попросят прочитать со смещением, выходящим за пределы диапазона [0,2^32-1], но сгенерирует OUT_OF_RANGE , если ее попросят прочитать со смещением за текущим. размер файла.

Между FAILED_PRECONDITION и OUT_OF_RANGE есть немалое совпадение. Мы рекомендуем использовать OUT_OF_RANGE (более конкретную ошибку), когда она применима, чтобы вызывающие абоненты, выполняющие итерацию по пробелу, могли легко найти ошибку OUT_OF_RANGE и определить, когда они завершат работу.

HTTP-сопоставление: 400 неверных запросов

UNIMPLEMENTED

Операция не реализована или не поддерживается/включена в этом сервисе.

HTTP-сопоставление: 501 не реализовано

INTERNAL

Внутренние ошибки. Это означает, что некоторые инварианты, ожидаемые базовой системой, были нарушены. Этот код ошибки зарезервирован для серьезных ошибок.

HTTP-сопоставление: 500 внутренняя ошибка сервера

UNAVAILABLE

В настоящее время услуга недоступна. Скорее всего, это временное состояние, которое можно исправить, повторив попытку с отсрочкой. Обратите внимание, что не всегда безопасно повторять неидемпотентные операции.

См. приведенные выше рекомендации для выбора между FAILED_PRECONDITION , ABORTED и UNAVAILABLE .

HTTP-сопоставление: служба 503 недоступна

DATA_LOSS

Невосстановимая потеря или повреждение данных.

HTTP-сопоставление: 500 внутренняя ошибка сервера