Códigos e tratamento de erros do Spanner

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

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

Quando uma solicitação falha, a API Spanner retorna um código de status HTTP 4xx ou 5xx que identifica generalmente a falha, além de 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 código de erro canônico (google.rpc.Code). Em erros JSON, esse 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, geralmente 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 transactional:
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, inserir 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 tempo 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. Uma possível causa é a execução de uma consulta que requer um índice ainda não definido. Não tente novamente sem resolver o problema.
INTERNAL O servidor retornou um erro. Algumas variantes 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 atualização de uma entidade ou consulta de 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 o Spanner ou a cota do projeto. Se você excedeu uma cota, não tente outra vez 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 no momento 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 suficientes podem ser convertidos neste erro. Confira se a solicitação é segura. Em seguida, tente usar a espera exponencial.