Package google.rpc

Índice

BadRequest

Descreve violações em uma solicitação do cliente. Esse tipo de erro se concentra nos aspectos sintáticos da solicitação.

Campos
field_violations[]

FieldViolation

Descreve todas as violações em uma solicitação do cliente.

FieldViolation

Um tipo de mensagem usado para descrever um único campo de solicitação inválida.

Campos
field

string

Um caminho que leva a um campo no corpo da solicitação. O valor será uma sequência de identificadores separados por pontos que identificam um campo de buffer de protocolo.

Considere o seguinte:

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;
}

Neste exemplo, em proto, field pode ter um dos seguintes valores:

  • full_name para uma violação no valor full_name
  • email_addresses[1].email por uma violação no campo email da primeira mensagem email_addresses
  • email_addresses[3].type[2] por uma violação no segundo valor type na terceira mensagem email_addresses.

Em JSON, os mesmos valores são representados como:

  • fullName para uma violação no valor fullName
  • emailAddresses[1].email por uma violação no campo email da primeira mensagem emailAddresses
  • emailAddresses[3].type[2] por uma violação no segundo valor type na terceira mensagem emailAddresses.
description

string

Uma descrição do motivo pelo qual o elemento de solicitação é inválido.
reason

string

O motivo do erro no nível do campo. Esse é um valor constante que identifica a causa próxima do erro no nível do campo. Ele precisa identificar exclusivamente o tipo de FieldViolation no escopo de google.rpc.ErrorInfo.domain. Ele precisa ter no máximo 63 caracteres e corresponder a uma expressão regular de [A-Z][A-Z0-9_]+[A-Z0-9], que representa UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

Fornece uma mensagem de erro localizada para erros no nível do campo que pode ser retornada com segurança ao consumidor da API.

Código

Códigos de erros canônicos para APIs gRPC.

Às vezes, vários códigos de erros podem ser aplicados. Os serviços retornam o código do erro mais específico aplicável. Por exemplo, dê preferência a OUT_OF_RANGE em vez de FAILED_PRECONDITION, se ambos os códigos se aplicarem. Da mesma maneira, dê preferência a NOT_FOUND ou ALREADY_EXISTS em vez de FAILED_PRECONDITION.

Tipos enumerados
OK

Não é um erro. Retornado quando bem-sucedido.

Mapeamento HTTP: 200 OK
CANCELLED

A operação foi cancelada, geralmente pelo chamador

Mapeamento HTTP: 499 Solicitação fechada pelo cliente
UNKNOWN

Erro desconhecido. Por exemplo, esse erro pode ser retornado quando um valor Status recebido de outro espaço de endereço pertence a um espaço de erro desconhecido nesse espaço de endereço. Além disso, os erros gerados por APIs que não retornam informações de erro suficientes podem ser convertidos neste erro.

Mapeamento HTTP: 500 Erro interno do servidor
INVALID_ARGUMENT

O cliente especificou um argumento inválido. Observe que isso é diferente de FAILED_PRECONDITION. INVALID_ARGUMENT indica argumentos problemáticos, independentemente do estado do sistema. Por exemplo, um nome de arquivo incorreto.

Mapeamento HTTP: 400 Solicitação inválida
DEADLINE_EXCEEDED

O prazo expirou antes do término da operação. Para operações que alteram o estado do sistema, este erro pode ser retornado mesmo que a operação tenha sido concluída com sucesso. Por exemplo, uma resposta bem-sucedida de um servidor pode ter atrasado tempo suficiente para que o prazo expirasse.

Mapeamento HTTP: 504 Tempo limite do gateway
NOT_FOUND

Alguma entidade solicitada não foi encontrada. Por exemplo, arquivo ou diretório.

Observação para desenvolvedores de servidor: se uma solicitação for negada para uma classe inteira de usuários, como a implementação gradual de recursos ou a lista não documentada de permissões, NOT_FOUND poderá ser usado. Se uma solicitação for negada para alguns usuários de uma classe, como o controle de acesso baseado em usuário, PERMISSION_DENIED precisará ser usado.

Mapeamento HTTP: 404 Não encontrado
ALREADY_EXISTS

A entidade que um cliente tentou criar já existe. Por exemplo, arquivo ou diretório.

Mapeamento HTTP: 409 Conflito
PERMISSION_DENIED

O autor da chamada não tem permissão para executar a operação especificada. PERMISSION_DENIED não pode ser usado para rejeições causadas pelo esgotamento de algum recurso. Em vez dele, use RESOURCE_EXHAUSTED para esses erros. PERMISSION_DENIED não poderá ser usado se o autor da chamada não for identificado. Em vez dele, use UNAUTHENTICATED para esses erros. Esse código do erro não indica que a solicitação seja válida nem que a entidade solicitada exista ou satisfaça outras condições prévias.

Mapeamento HTTP: 403 Proibido
UNAUTHENTICATED

A solicitação não tem credenciais válidas de autenticação para a operação.

Mapeamento HTTP: 401 Não autorizado
RESOURCE_EXHAUSTED

Houve o esgotamento de algum recurso, como uma cota por usuário. Também é possível que todo sistema de arquivos esteja sem espaço.

Mapeamento HTTP: 429 Há muitas solicitações
FAILED_PRECONDITION

A operação foi rejeitada porque o estado do sistema não é o necessário para a execução dela. Por exemplo, o diretório a ser excluído não está vazio, uma operação "rmdir" foi aplicada a um elemento que não é um diretório etc.

Os implementadores de serviços podem usar as diretrizes a seguir para decidir entre FAILED_PRECONDITION, ABORTED e UNAVAILABLE: (a) usar UNAVAILABLE se o cliente puder repetir apenas a chamada com falha. (b) Use ABORTED se o cliente precisar tentar novamente em um nível mais alto. Por exemplo, quando um teste e um conjunto especificado pelo cliente falha, indicando que o cliente precisa reiniciar uma sequência de leitura-modificação-gravação. (c) Use FAILED_PRECONDITION se o cliente não tentar novamente até que o estado do sistema seja explicitamente corrigido. Por exemplo, se houver falha em um "rmdir" porque o diretório não está vazio, FAILED_PRECONDITION será retornado, porque o cliente não precisa tentar novamente, a menos que os arquivos sejam excluídos do diretório.

Mapeamento HTTP: 400 Solicitação inválida
ABORTED

A operação foi cancelada. Isso ocorre normalmente devido a um problema de simultaneidade, como falha na verificação do sequenciador ou cancelamento da transação.

Consulte as diretrizes acima para decidir entre FAILED_PRECONDITION, ABORTED e UNAVAILABLE.

Mapeamento HTTP: 409 Conflito
OUT_OF_RANGE

Houve uma tentativa da operação depois do intervalo válido. Por exemplo, busca ou leitura após o fim do arquivo.

Diferentemente de INVALID_ARGUMENT, este erro indica um problema que poderá ser corrigido se o estado do sistema mudar. Por exemplo, um sistema de arquivos de 32 bits gerará INVALID_ARGUMENT se for solicitado a ler em um deslocamento fora do intervalo [0,2^32-1], mas gerará OUT_OF_RANGE se for solicitado a ler um deslocamento que ultrapasse o tamanho do arquivo atual.

Há alguma sobreposição entre FAILED_PRECONDITION e OUT_OF_RANGE. Recomendamos usar OUT_OF_RANGE (o erro mais específico) quando aplicável para que os autores da chamada que estão iterando por meio de um espaço possam procurar facilmente um erro OUT_OF_RANGE a fim de detectar quando tiverem concluído.

Mapeamento HTTP: 400 Solicitação inválida
UNIMPLEMENTED

A operação não foi implementada ou não é compatível nem está ativada neste serviço.

Mapeamento HTTP: 501 Não implementado
INTERNAL

Erros internos. Significa que algumas invariantes esperadas pelo sistema subjacente foram corrompidas. Este código do erro é reservado para erros graves.

Mapeamento HTTP: 500 Erro interno do servidor
UNAVAILABLE

Atualmente, o serviço não está disponível. Muito provavelmente, trata-se de uma condição temporária, que pode ser corrigida ao tentar novamente com uma retirada. Nem sempre é seguro repetir operações não idempotentes.

Consulte as diretrizes acima para decidir entre FAILED_PRECONDITION, ABORTED e UNAVAILABLE.

Mapeamento HTTP: 503 Serviço indisponível
DATA_LOSS

Perda ou corrupção irrecuperável de dados.

Mapeamento HTTP: 500 Erro interno do servidor

ErrorInfo

Descreve a causa do erro com detalhes estruturados.

Exemplo de erro ao entrar em contato com a API "pubsub.googleapis.com" quando ela não está ativada:

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

Essa resposta indica que a API pubsub.googleapis.com não está ativada.

Exemplo de um erro retornado ao tentar criar uma instância do Spanner em uma região que está fora de estoque:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
Campos
reason

string

O motivo do erro. Esse é um valor constante que identifica a causa próxima do erro. Os motivos dos erros são exclusivos em um domínio específico. Ele precisa ter no máximo 63 caracteres e corresponder a uma expressão regular de [A-Z][A-Z0-9_]+[A-Z0-9], que representa UPPER_SNAKE_CASE.
domain

string

O agrupamento lógico ao qual o "motivo" pertence. O domínio de erro normalmente é o nome de serviço registrado da ferramenta ou do produto que gera o erro. Exemplo: "pubsub.googleapis.com". Se o erro for gerado por alguma infraestrutura comum, o domínio do erro precisará ser um valor globalmente exclusivo que identifique a infraestrutura. Para a infraestrutura da API do Google, o domínio do erro é "googleapis.com".
metadata

map<string, string>

São outros detalhes estruturados sobre esse erro.

As chaves precisam corresponder a uma expressão regular de [a-z][a-zA-Z0-9-_]+, mas o ideal é que sejam lowerCamelCase. Além disso, eles precisam ter até 64 caracteres. Ao identificar o valor atual de um limite excedido, as unidades devem estar contidas na chave, não no valor. Por exemplo, em vez de {"instanceLimit": "100/request"}, deve ser retornado como {"instanceLimitPerRequest": "100"} se o cliente exceder o número de instâncias que podem ser criadas em uma única solicitação (lote).

Ajuda

Fornece links para documentação ou para realizar uma ação fora da banda.

Por exemplo, se uma verificação de cota falhar com um erro indicando que o projeto de chamada não ativou o serviço acessado, isso pode conter um URL que aponta diretamente para o lugar certo no console do desenvolvedor para alternar o bit.

Campos

LocalizedMessage

Fornece uma mensagem de erro localizada que pode ser retornada ao usuário e anexada a um erro de RPC.

Campos
locale

string

A localidade usada seguindo a especificação definida em https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Exemplos: "en-US", "fr-CH", "es-MX"
message

string

A mensagem de erro localizada na localidade acima.

PreconditionFailure

Descreve quais pré-condições falharam.

Por exemplo, se uma RPC falhar porque exigia o reconhecimento dos Termos de Serviço, ela poderá listar a violação dos Termos de Serviço na mensagem "PreconditionFailure".

Campos
violations[]

Violation

Descreve todas as violações de condição prévia.

Violação

Um tipo de mensagem usado para descrever uma única falha de condição prévia.

Campos
type

string

O tipo de PreconditionFailure. Recomendamos usar um tipo enumerado específico do serviço para definir os assuntos de violação de pré-condição compatíveis. Por exemplo, "TOS" para "violação dos Termos de Serviço".
subject

string

O assunto, em relação ao tipo, que falhou. Por exemplo, "google.com/cloud" em relação ao tipo "TOS" indica quais Termos de Serviço estão sendo referenciados.
description

string

Uma descrição de como a condição prévia falhou. Os desenvolvedores podem usar essa descrição para entender como corrigir a falha.

Por exemplo: "Termos de Serviço não aceitos".

QuotaFailure

Descreve como uma verificação de cota falhou.

Por exemplo, se um limite diário for excedido para o projeto de chamada, um serviço poderá responder com um detalhe QuotaFailure que contém o ID do projeto e a descrição do limite de cota excedido. Se o projeto de chamada não tiver ativado o serviço no console do desenvolvedor, um serviço poderá responder com o ID do projeto e definir service_disabled como "true".

Consulte também os tipos RetryInfo e Help para outros detalhes sobre como lidar com uma falha de cota.

Campos
violations[]

Violation

Descreve todas as violações de cota.

Violação

Um tipo de mensagem usado para descrever uma única violação de cota. Por exemplo, uma cota diária ou personalizada que foi excedida.

Campos
subject

string

O assunto em que a verificação de cota falhou. Por exemplo, "clientip:" ou "project:".
description

string

Uma descrição de como a verificação de cota falhou. Os clientes podem usar essa descrição para saber mais sobre a configuração de cota na documentação pública do serviço ou encontrar o limite de cota relevante para ajustar no console do desenvolvedor.

Por exemplo: "Serviço desativado" ou "Limite diário de operações de leitura excedido".
api_service

string

O serviço de API de que o QuotaFailure.Violation se origina. Em alguns casos, os problemas de cota têm origem em um serviço de API diferente daquele que foi chamado. Em outras palavras, uma dependência do serviço de API chamado pode ser a causa do QuotaFailure, e esse campo teria o nome do serviço de API de dependência.

Por exemplo, se a API chamada for a API Kubernetes Engine (container.googleapis.com) e ocorrer uma violação de cota na própria API Kubernetes Engine, esse campo será "container.googleapis.com". Por outro lado, se a violação de cota ocorrer quando a API Kubernetes Engine criar VMs na API Compute Engine (compute.googleapis.com), esse campo será "compute.googleapis.com".
quota_metric

string

A métrica da cota violada. Uma métrica de cota é um contador nomeado para medir o uso, como solicitações de API ou CPUs. Quando uma atividade ocorre em um serviço, como a alocação de máquinas virtuais, uma ou mais métricas de cota podem ser afetadas.

Por exemplo, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".
quota_id

string

O ID da cota violada. Também conhecido como "nome do limite", é o identificador exclusivo de uma cota no contexto de um serviço de API.

Por exemplo, "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions

map<string, string>

As dimensões da cota violada. Todas as cotas não globais são aplicadas a um conjunto de dimensões. Enquanto a métrica de cota define o que contar, as dimensões especificam para quais aspectos o contador deve ser incrementado.

Por exemplo, a cota "CPUs por região por família de VMs" impõe um limite à métrica "compute.googleapis.com/cpus_per_vm_family" nas dimensões "region" e "vm_family". Se a violação ocorreu na região "us-central1" e para a família de VMs "n1", as quota_dimensions seriam:

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

Quando uma cota é aplicada globalmente, quota_dimensions está sempre vazio.
quota_value

int64

O valor da cota aplicada no momento do QuotaFailure.

Por exemplo, se o valor da cota aplicada no momento do QuotaFailure no número de CPUs for "10", o valor desse campo vai refletir essa quantidade.
future_quota_value

int64

O novo valor de cota sendo lançado no momento da violação. Ao concluir o lançamento, esse valor será aplicado no lugar de "quota_value". Se não houver um lançamento em andamento no momento da violação, esse campo não será definido.

Por exemplo, se no momento da violação uma implantação estiver em andamento, mudando a cota de CPUs de 10 para 20, 20 será o valor desse campo.

RequestInfo

Contém metadados sobre a solicitação que os clientes podem anexar ao registrar um bug ou fornecer outras formas de feedback.

Campos
request_id

string

Uma string opaca que só pode ser interpretada pelo serviço que a gera. Por exemplo, ele pode ser usado para identificar solicitações nos registros do serviço.
serving_data

string

Todos os dados usados para atender a esta solicitação. Por exemplo, um stack trace criptografado que pode ser enviado de volta ao provedor de serviços para depuração.

ResourceInfo

Descreve o recurso que está sendo acessado.

Campos
resource_type

string

Um nome para o tipo de recurso acessado, por exemplo, "sql table", "cloud Storage bucket", "file", "Google calendar"; ou do tipo de URL do recurso, por exemplo, "type.googleapis.com/google.pubsub.v1.Topic".
resource_name

string

O nome do recurso que está sendo acessado. Por exemplo, o nome de uma agenda compartilhada: "example.com_4fghdhgsrgh@group.calendar.google.com", se o erro atual for google.rpc.Code.PERMISSION_DENIED.
owner

string

O proprietário do recurso (opcional). Por exemplo, "user:" ou "project:".
description

string

Descreve o erro encontrado ao acessar este recurso. Por exemplo, a atualização de um projeto na nuvem pode exigir a permissão writer no projeto do Play Console.

RetryInfo

Descreve quando os clientes podem repetir uma solicitação com falha. Os clientes podem ignorar a recomendação ou tentar de novo quando essas informações estiverem ausentes das respostas de erro.

É sempre recomendável que os clientes usem a espera exponencial ao tentar novamente.

Os clientes precisam esperar até que retry_delay tempo tenha passado desde o recebimento da resposta de erro antes de tentar novamente. Se as novas tentativas também falharem, os clientes deverão usar um esquema de espera exponencial para aumentar gradualmente o atraso entre as tentativas com base em retry_delay, até que um número máximo de tentativas ou um limite máximo de atraso seja atingido.

Campos
retry_delay

Duration

Os clientes precisam esperar pelo menos esse tempo entre as tentativas do mesmo pedido.

Status

O tipo Status define um modelo de erro lógico que é adequado a diferentes ambientes de programação, incluindo APIs REST e RPC. É usado por gRPC. Cada mensagem Status contém três partes de dados: código do erro, mensagem de erro e detalhes do erro.

É possível descobrir mais sobre esse modelo de erro e como trabalhar com ele no Guia de projeto da API.

Campos
code

int32

O código de status, que precisa ser um valor de enumeração de google.rpc.Code.
message

string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro para o usuário precisa ser localizada e enviada no campo google.rpc.Status.details, ou localizada pelo cliente.
details[]

Any

Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem.