Package google.rpc

Índice

BadRequest

Descreve violações num pedido de cliente. Este tipo de erro centra-se nos aspetos sintáticos do pedido.

Campos
field_violations[]

FieldViolation

Descreve todas as violações num pedido do cliente.

FieldViolation

Um tipo de mensagem usado para descrever um único campo de pedido inválido.

Campos
field

string

Um caminho que leva a um campo no corpo do pedido. O valor é 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 assumir um dos seguintes valores:

  • full_name por uma violação no valor full_name
  • email_addresses[1].email para 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 da seguinte forma:

  • fullName por uma violação no valor fullName
  • emailAddresses[1].email para 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 pedido é inválido.
reason

string

O motivo do erro ao nível do campo. Este é um valor constante que identifica a causa próxima do erro ao nível do campo. Deve identificar de forma exclusiva o tipo de FieldViolation no âmbito de google.rpc.ErrorInfo.domain. Este campo deve ter, no máximo, 63 carateres 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 ao nível do campo que é seguro devolver ao consumidor da API.

Código

Os códigos de erro canónicos para APIs gRPC.

Por vezes, podem aplicar-se vários códigos de erro. Os serviços devem devolver o código de erro mais específico que se aplica. Por exemplo, prefira OUT_OF_RANGE a FAILED_PRECONDITION se ambos os códigos se aplicarem. Da mesma forma, prefira NOT_FOUND ou ALREADY_EXISTS em vez de FAILED_PRECONDITION.

Enumerações
OK

Não é um erro; é devolvido em caso de êxito.

Mapeamento HTTP: 200 OK
CANCELLED

A operação foi cancelada, normalmente, pelo autor da chamada.

Mapeamento HTTP: 499 Cliente fechou pedido
UNKNOWN

Erro desconhecido. Por exemplo, este erro pode ser devolvido quando um valor Status recebido de outro espaço de endereço pertence a um espaço de erro que não é conhecido neste espaço de endereço. Além disso, os erros gerados por APIs que não devolvem 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. Tenha em atenção que isto difere de FAILED_PRECONDITION. INVALID_ARGUMENT indica argumentos problemáticos independentemente do estado do sistema (por exemplo, um nome de ficheiro com formato incorreto).

Mapeamento HTTP: 400 Pedido errado
DEADLINE_EXCEEDED

O prazo expirou antes de a operação poder ser concluída. Para operações que alteram o estado do sistema, este erro pode ser devolvido mesmo que a operação tenha sido concluída com êxito. Por exemplo, uma resposta bem-sucedida de um servidor pode ter sofrido um atraso suficiente para que o prazo expire.

Mapeamento de HTTP: 504 Tempo limite do gateway
NOT_FOUND

Não foi encontrada alguma entidade pedida (por exemplo, um ficheiro ou um diretório).

Nota para os programadores de servidores: se um pedido for recusado para uma classe inteira de utilizadores, como a implementação gradual de funcionalidades ou uma lista de autorizações não documentada, pode usar-se o NOT_FOUND. Se um pedido for recusado para alguns utilizadores numa classe de utilizadores, como o controlo de acesso baseado no utilizador, tem de usar PERMISSION_DENIED.

Mapeamento HTTP: 404 Not Found
ALREADY_EXISTS

A entidade que um cliente tentou criar (por exemplo, um ficheiro ou um diretório) já existe.

Mapeamento HTTP: 409 Conflito
PERMISSION_DENIED

O autor da chamada não tem autorização para executar a operação especificada. PERMISSION_DENIED não deve ser usado para rejeições causadas pelo esgotamento de algum recurso (use RESOURCE_EXHAUSTED em alternativa para esses erros). PERMISSION_DENIED não pode ser usado se não for possível identificar o autor da chamada (use UNAUTHENTICATED para esses erros). Este código de erro não implica que o pedido seja válido ou que a entidade pedida exista ou satisfaça outras pré-condições.

Mapeamento HTTP: 403 Proibido
UNAUTHENTICATED

O pedido não tem credenciais de autenticação válidas para a operação.

Mapeamento HTTP: 401 Não autorizado
RESOURCE_EXHAUSTED

Algum recurso foi esgotado, talvez uma quota por utilizador ou talvez o sistema de ficheiros completo esteja sem espaço.

Mapeamento HTTP: 429 Demasiados pedidos
FAILED_PRECONDITION

A operação foi rejeitada porque o sistema não se encontra num estado necessário para a execução da operação. Por exemplo, o diretório a eliminar não está vazio, é aplicada uma operação rmdir a um não diretório, etc.

Os implementadores de serviços podem usar as seguintes diretrizes para decidir entre FAILED_PRECONDITION, ABORTED e UNAVAILABLE: (a) Use UNAVAILABLE se o cliente puder repetir apenas a chamada com falha. (b) Use ABORTED se o cliente deve tentar novamente a um nível superior. Por exemplo, quando um teste e definição especificados pelo cliente falham, o que indica que o cliente deve reiniciar uma sequência de leitura-modificação-escrita. (c) Use FAILED_PRECONDITION se o cliente não deve tentar novamente até que o estado do sistema tenha sido explicitamente corrigido. Por exemplo, se um "rmdir" falhar porque o diretório não está vazio, deve ser devolvido FAILED_PRECONDITION, uma vez que o cliente não deve tentar novamente, a menos que os ficheiros sejam eliminados do diretório.

Mapeamento HTTP: 400 Pedido errado
ABORTED

A operação foi interrompida, normalmente devido a um problema de simultaneidade, como uma falha na verificação do sequenciador ou uma interrupção da transação.

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

Mapeamento HTTP: 409 Conflito
OUT_OF_RANGE

A operação foi tentada fora do intervalo válido. Por exemplo, procurar ou ler após o fim do ficheiro.

Ao contrário de INVALID_ARGUMENT, este erro indica um problema que pode ser corrigido se o estado do sistema for alterado. Por exemplo, um sistema de ficheiros de 32 bits gera INVALID_ARGUMENT se lhe for pedido que leia num desvio que não esteja no intervalo [0,2^32-1], mas gera OUT_OF_RANGE se lhe for pedido que leia a partir de um desvio após o tamanho do ficheiro atual.

Existe alguma sobreposição entre FAILED_PRECONDITION e OUT_OF_RANGE. Recomendamos a utilização de OUT_OF_RANGE (o erro mais específico) quando se aplica, para que os autores de chamadas que estão a iterar num espaço possam procurar facilmente um erro OUT_OF_RANGE para detetar quando terminam.

Mapeamento HTTP: 400 Pedido errado
UNIMPLEMENTED

A operação não está implementada ou não é suportada/ativada neste serviço.

Mapeamento HTTP: 501 Não implementado
INTERNAL

Erros internos. Isto significa que algumas invariantes esperadas pelo sistema subjacente foram violadas. Este código de erro está reservado para erros graves.

Mapeamento HTTP: 500 Erro interno do servidor
UNAVAILABLE

O serviço está atualmente indisponível. Esta é provavelmente uma condição temporária que pode ser corrigida ao tentar novamente com uma recusa. Tenha em atenção que 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 de dados irrecuperável ou corrupção de dados.

Mapeamento HTTP: 500 Erro interno do servidor

LocalizedMessage

Fornece uma mensagem de erro localizada que é segura para devolver ao utilizador e que pode ser anexada a um erro de RPC.

Campos
locale

string

O local usado de acordo com 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 no local acima.

Estado

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

Pode saber mais acerca deste modelo de erro e como trabalhar com ele no guia de design de APIs.

Campos
code

int32

O código de estado, que deve ser um valor enum de google.rpc.Code.
message

string

Uma mensagem de erro destinada a programadores, que deve estar em inglês. Todas as mensagens de erro apresentadas ao utilizador devem ser localizadas e enviadas no campo google.rpc.Status.details ou localizadas pelo cliente.
details[]

Any

Uma lista de mensagens que contêm os detalhes do erro. Existe um conjunto comum de tipos de mensagens para as APIs usarem.