Índice
País
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
.
Enums | |
---|---|
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 Mapeamento HTTP: 500 Erro interno do servidor |
INVALID_ARGUMENT |
O cliente especificou um argumento inválido. Observe que isso é diferente de 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 de permissões não documentada de permissões, 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. 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 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 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 Há alguma sobreposição entre 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. Consulte as diretrizes acima para decidir entre Mapeamento HTTP: 503 Serviço indisponível |
DATA_LOSS |
Perda ou corrupção irrecuperável de dados. Mapeamento HTTP: 500 Erro interno do servidor |
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
.Quando alguns erros de API são armazenados em registros, a mensagem
Status
pode ser usada diretamente após qualquer remoção necessária por motivos de segurança/privacidade.
Campos | |
---|---|
code |
O código de status, que precisa ser um valor de enumeração de |
message |
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 |
details[] |
Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem. |