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. O modelo de erro foi projetado para ser:

  • simples de usar e entender para a maioria dos usuários;
  • flexível o suficiente para atender às necessidades imprevistas.

Visão geral

A mensagem Status contém três dados: código de erro, mensagem de erro e detalhes do erro. O código de erro precisa ser um valor de enum google.rpc.Code, mas pode aceitar códigos de erro adicionais, se necessário. A mensagem de erro é uma mensagem em inglês que ajuda o desenvolvedor a entender e resolver o erro. Se uma mensagem de erro localizada para o usuário for necessária, coloque-a nos detalhes do erro ou faça a localização no cliente. Os detalhes opcionais do erro podem conter informações arbitrárias sobre ele. Há um conjunto predefinido de tipos de detalhes de erro no pacote google.rpc que pode ser usado para condições de erro comuns.

Mapeamento de linguagem

A mensagem Status é a representação lógica do modelo de erro, mas não é necessariamente o formato de transmissão real. Quando a mensagem Status é exposta em diferentes bibliotecas de cliente e protocolos de transmissão, ela pode ser mapeada de maneira diferente. Por exemplo, talvez ela seja mapeada para algumas exceções em Java, mas com probabilidade maior para alguns códigos de erro em C.

Outros usos

O modelo de erro e a mensagem Status podem ser usados em vários ambientes, com ou sem APIs, para proporcionar uma experiência de desenvolvedor consistente em diferentes ambientes.

Os exemplos de uso desse modelo de erro incluem:

  • erros parciais. Se um serviço precisar retornar erros parciais ao cliente, ele poderá incorporar o Status na resposta normal para indicar os erros parciais.

  • erros de fluxo de trabalho. Um fluxo de trabalho típico tem várias etapas. Cada etapa pode ter uma mensagem Status para o relatório de erros.

  • Operações em lote. Se um cliente usar solicitação em lote e resposta em lote, a mensagem Status será usada diretamente dentro da resposta em lote, uma para cada sub-resposta de erro.

  • Operações assíncronas. Se uma chamada de API incorpora resultados de operações assíncronas na resposta, o status dessas operações precisa ser representado diretamente usando a mensagem Status.

  • Geração de registros. Quando alguns erros de API são armazenados em registros, a mensagem de Status pode ser usada diretamente após qualquer remoção necessária por motivos de segurança/privacidade.

Representação JSON 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ],
}
Campos
code

number

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[]

object

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

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.