Code

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

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

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

Это не ошибка; возвращено в случае успеха.

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

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 Внутренняя ошибка сервера