Package google.rpc

Индекс

BadRequest

Описывает нарушения в запросе клиента. Этот тип ошибки фокусируется на синтаксических аспектах запроса.

Поля
field_violations[]

FieldViolation

Описывает все нарушения в запросе клиента.

Нарушение правил игры на поле

Тип сообщения, используемый для описания одного некорректного поля запроса.

Поля
field

string

Путь, ведущий к полю в теле запроса. Значение будет представлять собой последовательность идентификаторов, разделенных точками, которые идентифицируют поле протокола буферизации.

Рассмотрим следующее:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

В этом примере field в протоколе может принимать одно из следующих значений:

  • full_name для нарушения в значении full_name
  • email_addresses[1].email для нарушения в поле email первого сообщения email_addresses
  • email_addresses[3].type[2] для нарушения второго значения type в третьем сообщении email_addresses .

В формате JSON те же значения представляются следующим образом:

  • fullName для нарушения в значении fullName
  • emailAddresses[1].email для нарушения в поле email первого сообщения emailAddresses
  • emailAddresses[3].type[2] для нарушения второго значения type в третьем сообщении emailAddresses .
description

string

Описание того, почему элемент запроса является некорректным.

reason

string

Причина ошибки на уровне поля. Это постоянное значение, определяющее непосредственную причину ошибки на уровне поля. Оно должно однозначно идентифицировать тип нарушения поля в рамках области действия google.rpc.ErrorInfo.domain. Длина значения не должна превышать 63 символа, и оно должно соответствовать регулярному выражению [AZ][A-Z0-9_]+[A-Z0-9] , что соответствует регистру UPPER_SNAKE_CASE.

localized_message

LocalizedMessage

Предоставляет локализованное сообщение об ошибке для ошибок на уровне полей, которое можно безопасно вернуть потребителю API.

Код

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

ErrorInfo

Описывает причину ошибки с подробным описанием.

Пример ошибки при обращении к API "pubsub.googleapis.com", если он не включен:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

Этот ответ указывает на то, что API pubsub.googleapis.com не включен.

Пример ошибки, которая возвращается при попытке создать экземпляр Spanner в регионе, где товар отсутствует на складе:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
Поля
reason

string

Причина ошибки. Это постоянное значение, определяющее непосредственную причину ошибки. Причины ошибок уникальны в рамках определенной области ошибок. Длина сообщения должна составлять не более 63 символов и соответствовать регулярному выражению [AZ][A-Z0-9_]+[A-Z0-9] , что обозначает UPPER_SNAKE_CASE.

domain

string

Логическая группа, к которой относится «причина». Домен ошибки обычно представляет собой зарегистрированное имя сервиса инструмента или продукта, генерирующего ошибку. Пример: «pubsub.googleapis.com». Если ошибка генерируется какой-либо общей инфраструктурой, домен ошибки должен быть глобально уникальным значением, идентифицирующим эту инфраструктуру. Для инфраструктуры Google API доменом ошибки является «googleapis.com».

metadata

map<string, string>

Дополнительные структурированные сведения об этой ошибке.

Ключи должны соответствовать регулярному выражению [az][a-zA-Z0-9-_]+ , но в идеале должны быть в нижнем регистре (lowerCamelCase). Кроме того, их длина должна быть ограничена 64 символами. При определении текущего значения превышенного лимита единицы измерения должны содержаться в ключе, а не в значении. Например, вместо {"instanceLimit": "100/request"} следует возвращать {"instanceLimitPerRequest": "100"} , если клиент превышает количество экземпляров, которые могут быть созданы в одном (пакетном) запросе.

Помощь

Предоставляет ссылки на документацию или для выполнения внеплановых действий.

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

Поля

Локализованное сообщение

Предоставляет локализованное сообщение об ошибке, которое можно безопасно вернуть пользователю и которое может быть прикреплено к ошибке RPC.

Поля
locale

string

Используется локаль в соответствии со спецификацией, описанной по адресу https://www.rfc-editor.org/rfc/bcp/bcp47.txt . Примеры: "en-US", "fr-CH", "es-MX".

message

string

Локализованное сообщение об ошибке в указанной выше языковой версии.

RequestInfo

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

Поля
request_id

string

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

serving_data

string

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

Статус

Тип Status определяет логическую модель ошибок, подходящую для различных сред программирования, включая REST API и RPC API. Он используется в gRPC . Каждое сообщение Status содержит три элемента данных: код ошибки, сообщение об ошибке и подробности ошибки.

Более подробную информацию об этой модели ошибок и способах работы с ней вы найдете в Руководстве по проектированию API .

Поля
code

int32

Код состояния, который должен быть значением перечисления google.rpc.Code .

message

string

Сообщение об ошибке, предназначенное для разработчика, должно быть на английском языке. Любое сообщение об ошибке, предназначенное для пользователя, должно быть локализовано и отправлено в поле google.rpc.Status.details или локализовано клиентом.

details[]

Any

Список сообщений, содержащих подробную информацию об ошибке. Существует общий набор типов сообщений, используемых API.