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

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

Предварительное условиеСбой

Описывает, какие предварительные условия не были выполнены.

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

Поля
violations[]

Violation

Описывает все нарушения предварительных условий.

Нарушение

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

Поля
type

string

Тип PreconditionFailure. Мы рекомендуем использовать перечислимый тип, специфичный для сервиса, для определения поддерживаемых субъектов нарушения предварительных условий. Например, "TOS" для "Нарушение Условий предоставления услуг".

subject

string

Укажите тему, в зависимости от типа запроса, который не сработал. Например, "google.com/cloud" в контексте типа "Условия предоставления услуг" укажет, на какие именно условия предоставления услуг делается ссылка.

description

string

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

Например: «Условия предоставления услуг не приняты».

QuotaFailure

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

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

Дополнительные сведения об обработке сбоя квоты см. в разделах RetryInfo и Help types.

Поля
violations[]

Violation

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

Нарушение

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

Поля
subject

string

Тема, по которой проверка квоты не удалась. Например, "clientip: или "проект: «.

description

string

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

Например: «Сервис отключен» или «Превышен суточный лимит операций чтения».

api_service

string

API-сервис, от которого возникает ошибка QuotaFailure.Violation . В некоторых случаях проблемы с квотами возникают из-за API-сервиса, отличного от того, который был вызван. Другими словами, зависимость вызываемого API-сервиса может быть причиной QuotaFailure , и в этом поле будет указано имя зависимого API-сервиса.

Например, если вызываемый API — это API Kubernetes Engine (container.googleapis.com), и в самом API Kubernetes Engine происходит нарушение квоты, то это поле будет иметь значение "container.googleapis.com". С другой стороны, если нарушение квоты происходит при создании виртуальных машин API Kubernetes Engine в API Compute Engine (compute.googleapis.com), то это поле будет иметь значение "compute.googleapis.com".

quota_metric

string

Показатель нарушенной квоты. Показатель квоты — это именованный счетчик для измерения использования ресурсов, например, запросов API или процессоров. Когда в сервисе происходит какое-либо действие, например, выделение ресурсов виртуальной машины, это может повлиять на один или несколько показателей квоты.

Например, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".

quota_id

string

Идентификатор нарушенной квоты. Также известный как «имя лимита», это уникальный идентификатор квоты в контексте API-сервиса.

Например, "CPUS-PER-VM-FAMILY-per-project-region".

quota_dimensions

map<string, string>

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

Например, квота "ЦП на регион на семейство ВМ" устанавливает ограничение на метрику "compute.googleapis.com/cpus_per_vm_family" по параметрам "region" и "vm_family". И если нарушение произошло в регионе "us-central1" и для семейства ВМ "n1", то значение quota_dimensions будет следующим:

{ "region": "us-central1", "vm_family": "n1", }

Если квота применяется глобально, параметр quota_dimensions всегда будет пустым.

quota_value

int64

Значение принудительной квоты на момент QuotaFailure .

Например, если значение квоты, установленное на момент сбоя QuotaFailure для количества процессоров, равно "10", то значение этого поля будет отражать это число.

future_quota_value

int64

Новое значение квоты, внедряемое на момент нарушения. По завершении внедрения это значение будет применяться вместо quota_value. Если на момент нарушения внедрение не ведется, это поле не устанавливается.

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

RequestInfo

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

Поля
request_id

string

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

serving_data

string

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

ResourceInfo

Описывает ресурс, к которому осуществляется доступ.

Поля
resource_type

string

Название типа ресурса, к которому осуществляется доступ, например, "sql table", "cloud storage bucket", "file", "Google calendar"; или URL-адрес типа ресурса: например, "type.googleapis.com/google.pubsub.v1.Topic".

resource_name

string

Имя ресурса, к которому осуществляется доступ. Например, имя общего календаря: "example.com _4fghdhgsrgh@group.calendar.google.com" , если текущая ошибка — google.rpc.Code.PERMISSION_DENIED .

owner

string

Владелец ресурса (необязательно). Например, "user: или "проект: «.

description

string

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

Информация о повторной попытке

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

Клиентам всегда рекомендуется использовать экспоненциальную задержку при повторных попытках.

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

Поля
retry_delay

Duration

Клиентам следует выждать не менее этого времени между повторными попытками отправки одного и того же запроса.

Статус

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

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

Поля
code

int32

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

message

string

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

details[]

Any

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