Status

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 . 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 necessidades inesperadas

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 deve ser um valor enum de google.rpc.Code , mas pode aceitar códigos de erro adicionais, se necessário. A mensagem de erro deve ser uma mensagem em inglês voltada para o desenvolvedor que ajude os desenvolvedores a entender e resolver o erro. Se for necessária uma mensagem de erro localizada voltada para o usuário, coloque a mensagem localizada nos detalhes do erro ou localize-a no cliente. Os detalhes opcionais do erro podem conter informações arbitrárias sobre o erro. 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 real da ligação. Quando a mensagem Status é exposta em diferentes bibliotecas de clientes e diferentes protocolos de ligação, ela pode ser mapeada de maneira diferente. Por exemplo, provavelmente será mapeado para algumas exceções em Java, mas é mais provável que seja mapeado 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 fornecer uma experiência consistente ao desenvolvedor em diferentes ambientes.

Exemplos de usos deste 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 possui várias etapas. Cada etapa pode ter uma mensagem Status para relatório de erros.

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

  • Operações assíncronas. Se uma chamada de API incorporar resultados de operação assíncrona em sua resposta, o status dessas operações deverá ser representado diretamente usando a mensagem Status .

  • Exploração madeireira. Se alguns erros de API forem armazenados em logs, a mensagem Status poderá 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 deve ser um valor enum de google.rpc.Code .

message

string

Uma mensagem de erro voltada ao desenvolvedor, que deve estar em inglês. Qualquer mensagem de erro voltada ao usuário deve ser localizada e enviada no campo google.rpc.Status.details ou localizada pelo cliente.

details[]

object

Uma lista de mensagens que contêm os detalhes do erro. Há um conjunto comum de tipos de mensagens para uso pelas APIs.

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