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 Client Closed Request
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 solicitada (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 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 deve 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 através de um 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 Not Implemented
INTERNAL
Erros internos. Isto significa que algumas invariantes esperadas pelo sistema subjacente foram quebradas. 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
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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-21 UTC."],[[["\u003cp\u003eThe document defines \u003ccode\u003eCode\u003c/code\u003e, an enum for canonical error codes used in gRPC APIs, and advises selecting the most specific error code when multiple codes apply.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eCode\u003c/code\u003e enum includes various error types like \u003ccode\u003eOK\u003c/code\u003e, \u003ccode\u003eCANCELLED\u003c/code\u003e, \u003ccode\u003eUNKNOWN\u003c/code\u003e, \u003ccode\u003eINVALID_ARGUMENT\u003c/code\u003e, \u003ccode\u003eNOT_FOUND\u003c/code\u003e, \u003ccode\u003ePERMISSION_DENIED\u003c/code\u003e, \u003ccode\u003eUNAUTHENTICATED\u003c/code\u003e, \u003ccode\u003eRESOURCE_EXHAUSTED\u003c/code\u003e, \u003ccode\u003eINTERNAL\u003c/code\u003e, and more, each with a brief description and HTTP mapping.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eStatus\u003c/code\u003e message type provides a structured way to communicate errors, containing a status \u003ccode\u003ecode\u003c/code\u003e, a developer-facing \u003ccode\u003emessage\u003c/code\u003e, and a list of \u003ccode\u003edetails\u003c/code\u003e for additional context.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eStatus\u003c/code\u003e error messages use a numerical code, a textual message, and can include additional details to thoroughly describe errors in various programming environments.\u003c/p\u003e\n"]]],[],null,["# Package google.rpc\n\nIndex\n-----\n\n- [Code](/distributed-cloud/hosted/docs/latest/gdch/apis/vertex-ai/ocr/rpc/google.rpc#google.rpc.Code) (enum)\n- [Status](/distributed-cloud/hosted/docs/latest/gdch/apis/vertex-ai/ocr/rpc/google.rpc#google.rpc.Status) (message)\n\nCode\n----\n\nThe canonical error codes for gRPC APIs.\n\nSometimes multiple error codes may apply. Services should return the most specific error code that applies. For example, prefer `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply. Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`.\n\nStatus\n------\n\nThe `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details.\n\nYou can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors)."]]
