Códigos de erros e tratamento de erros do Spanner

Nesta página, descrevemos os códigos de erro do Spanner e as ações recomendadas para e lidar com esses erros. As APIs do Google, incluindo o Spanner, usam o códigos de erro canônicos definidos por google.rpc.Code.

Quando uma solicitação do Spanner é bem-sucedida, a API retorna uma solicitação HTTP Código de status 200 OK junto com os dados solicitados no corpo da resposta.

Quando uma solicitação falha, a API Spanner retorna uma solicitação Código de status 4xx ou 5xx que identifica de forma genérica a falha, bem como uma resposta que fornece informações mais específicas sobre os erros que causaram a falha.

O objeto de resposta contém um único campo error. O valor dele contém os seguintes elementos:

Elemento Descrição
code Um código de status HTTP que identifica a falha na solicitação de forma genérica.
message Informações específicas sobre a falha da solicitação.
status O código de erro canônico (google.rpc.Code) de APIs do Google. Os códigos que podem ser retornados pela API Spanner estão listados em Códigos de erro.

Se uma solicitação feita com o tipo de conteúdo application/x-protobuf gerar erro, ela retornará uma mensagem google.rpc.Status serializada como payload.

Códigos de erro

A maneira recomendada de classificar erros é inspecionar o valor do atributo código de erro canônico (google.rpc.Code). Em erros de JSON, este código aparece no campo status. Em erros application/x-protobuf, ele está no campo code.

Código do erro Descrição Ação recomendada
ABORTED A operação foi cancelada, normalmente devido a um problema de simultaneidade, como falha na verificação do sequenciador ou cancelamento da transação. Indica que a solicitação entrou em conflito com outra solicitação. Para uma confirmação não transacional:
repita a solicitação ou estruture suas entidades para reduzir a contenção.

Para solicitações que fazem parte de uma confirmação transacional:
repita toda a transação ou estruture suas entidades para reduzir a contenção.
ALREADY_EXISTS A entidade que um cliente tentou criar já existe (por exemplo, inserindo uma linha com uma chave primária existente). Não tente novamente sem resolver o problema.
CANCELLED A operação foi cancelada, geralmente pelo chamador Repita a operação.
DEADLINE_EXCEEDED O prazo expirou antes do término da operação. Investigue se o prazo é suficiente. Use um prazo correspondente ao horário real em que uma resposta é útil. Observe que, para operações que alteram o estado do sistema, um erro pode ser retornado mesmo que a operação tenha sido concluída com êxito.

Confira dicas em Resolver erros de prazo excedido.
FAILED_PRECONDITION A operação foi rejeitada porque uma pré-condição para a solicitação não foi atendida. O campo de mensagem na resposta de erro fornece informações sobre essa condição. Por exemplo, leitura ou consulta de um carimbo de data/hora que excedeu a inatividade máxima dele. Não tente novamente sem resolver o problema.
INTERNAL O servidor retornou um erro. Algumas invariantes esperadas pelo sistema subjacente foram corrompidas. Não tente novamente a menos que você entenda a circunstância específica e a causa do erro.
INVALID_ARGUMENT O cliente especificou um valor inválido. O campo de mensagem na resposta de erro fornece informações sobre o valor inválido. Não tente novamente sem resolver o problema.
NOT_FOUND Indica que alguma entidade solicitada, como atualizar uma entidade ou consultar uma tabela ou coluna, não existe. Não tente novamente sem resolver o problema.
OUT_OF_RANGE Houve uma tentativa da operação depois do intervalo válido. Não tente novamente sem resolver o problema.
PERMISSION_DENIED O usuário não está autorizado a fazer a solicitação. Não tente novamente sem resolver o problema.
RESOURCE_EXHAUSTED Alguns recursos foram esgotados. Talvez o projeto tenha excedido a cota ou todo o sistema de arquivos esteja sem espaço. Verifique se você não excedeu a cota do projeto ou do Spanner. Se você excedeu uma cota, não tente novamente sem corrigir o problema.

Caso contrário, tente novamente com a espera exponencial.
UNAUTHENTICATED A solicitação não tem credenciais válidas de autenticação para a operação. Não tente novamente sem resolver o problema.
UNAVAILABLE O servidor não está disponível. Tente novamente usando a espera exponencial. Nem sempre é seguro repetir operações não idempotentes.
UNIMPLEMENTED A operação não foi implementada ou não é compatível nem está ativada neste serviço. Não tente novamente sem resolver o problema.
UNKNOWN O servidor retornou um erro desconhecido. Os erros gerados por APIs que não retornam informações de erro suficientes podem ser convertidos nesse erro. Verifique se a solicitação é segura. Em seguida, tente usar a espera exponencial.