Códigos de erro do Spanner

Esta página descreve os códigos de erro do Spanner e as ações recomendadas para resolver estes erros. As APIs Google, incluindo o Spanner, usam os códigos de erro canónicos definidos por google.rpc.Code.

Quando um pedido do Spanner é bem-sucedido, a API devolve um código de estado HTTP 200 OK juntamente com os dados pedidos no corpo da resposta.

Quando um pedido falha, a API Spanner devolve um código de estado HTTP 4xx ou 5xx que identifica genericamente 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 cujo valor contém os seguintes elementos:

Elemento Descrição
code Um código de estado HTTP que identifica genericamente a falha do pedido.
message Informações específicas sobre a falha do pedido.
status O código de erro canónico (google.rpc.Code) para as APIs Google. Os códigos que podem ser devolvidos pela API Spanner estão listados em Códigos de erro.

Se uma solicitação feita com um tipo de conteúdo de application/x-protobuf resultar num erro, devolve uma mensagem google.rpc.Status serializada como a carga útil.

Códigos de erro

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

Código de erro Descrição Ação recomendada
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. Indica que o pedido entrou em conflito com outro pedido. Para uma confirmação não transacional:
tente novamente o pedido ou estruture as suas entidades para reduzir a contenção.

Para pedidos que fazem parte de uma confirmação transacional:
tente novamente toda a transação ou estruture as 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 corrigir o problema.
CANCELLED A operação foi cancelada, normalmente, pelo autor da chamada. Repita a operação.
DEADLINE_EXCEEDED O prazo expirou antes de a operação poder ser concluída. Investigue se o prazo é suficiente. Use um prazo correspondente à hora real em que uma resposta é útil. Tenha em atenção que, para operações que alteram o estado do sistema, pode ser devolvido um erro, mesmo que a operação tenha sido concluída com êxito.

Para ver sugestões, consulte o artigo Resolva problemas de erros de prazo excedido.
FAILED_PRECONDITION A operação foi rejeitada porque não foi cumprida uma pré-condição para o pedido. O campo de mensagem na resposta de erro fornece informações sobre a pré-condição que falhou. Por exemplo, ler ou consultar a partir de uma data/hora que excedeu a obsolescência máxima da data/hora. Não tente novamente sem corrigir o problema.
INTERNAL O servidor devolveu um erro. Algumas invariantes esperadas pelo sistema subjacente foram quebradas. Não volte a tentar, a menos que compreenda 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 que era inválido. Não tente novamente sem corrigir o problema.
NOT_FOUND Indica que alguma entidade pedida, como a atualização de uma entidade ou a consulta de uma tabela ou uma coluna, não existe. Não tente novamente sem corrigir o problema.
OUT_OF_RANGE A operação foi tentada fora do intervalo válido. Não tente novamente sem corrigir o problema.
PERMISSION_DENIED O utilizador não tinha autorização para fazer o pedido. Não tente novamente sem corrigir o problema.
RESOURCE_EXHAUSTED Alguns recursos foram esgotados.

Para o plano de administrador, é possível que o projeto tenha excedido a respetiva quota ou que todo o sistema de ficheiros esteja sem espaço.

Para o plano de dados, isto pode acontecer se os seus nós do Spanner estiverem sobrecarregados.

Para mais informações, consulte também os códigos de erro relacionados com a sessão.		 Para o plano de administrador, verifique se não excedeu a sua quota do Spanner ou do projeto. Se excedeu uma quota, peça um aumento da quota ou aguarde que a quota seja reposta antes de tentar novamente. Configure as repetições para usar o recuo exponencial.

Para o plano de dados, verifique se os nós do Spanner não excederam a respetiva capacidade. O Spanner tenta novamente estes erros na biblioteca de cliente. Se todas as novas tentativas falharem, consulte Erros do mecanismo de controlo de fluxo.

Em geral, se a sua aplicação estiver a ter erros RESOURCE_EXHAUSTED, trate a situação como um erro UNAVAILABLE e tente novamente com um recuo exponencial.
UNAUTHENTICATED O pedido não tem credenciais de autenticação válidas para a operação. Não tente novamente sem corrigir o problema.
UNAVAILABLE O servidor está indisponível. Tente novamente com retirada exponencial. Tenha em atenção que nem sempre é seguro repetir operações não idempotentes.
UNIMPLEMENTED A operação não está implementada ou não é suportada/ativada neste serviço. Não tente novamente sem corrigir o problema.
UNKNOWN O servidor devolveu um erro desconhecido. Os erros gerados por APIs que não devolvem informações de erro suficientes podem ser convertidos neste erro. Verifique se o seu pedido é seguro. Em seguida, tente novamente com retirada exponencial.

Erros de sessão

O Spanner usa sessões para gerir as interações entre a sua aplicação e a base de dados. As sessões representam uma ligação à base de dados e facilitam operações como leituras e escritas.

Os erros comuns relacionados com a sessão que a sua aplicação pode encontrar incluem:

Sessão não encontrada

O erro Session not found ocorre quando a sua aplicação tenta usar uma sessão que já não existe. Isto pode acontecer por vários motivos.

  • A sua aplicação cliente pode eliminar explicitamente uma sessão. Por exemplo, fechar um cliente de base de dados no seu código ou chamar a API deleteSessions remove diretamente a sessão. Se não usar uma das bibliotecas de cliente do Spanner, crie uma nova sessão quando este erro ocorrer. Adicione a nova sessão ao conjunto de sessões e remova a sessão eliminada do conjunto.

  • O Spanner também elimina automaticamente as sessões em determinadas condições.

    • Elimina uma sessão se permanecer inativa durante mais de uma hora. Isto pode ocorrer em tarefas de fluxo de dados em que o processamento a jusante demora mais tempo do que o limite de tempo limite de inatividade da sessão. Se estiver a usar uma tarefa do Dataflow, adicione uma operação de transformação Reshuffleapós a leitura do Spanner no pipeline do Dataflow. Isto pode ajudar a separar a operação de leitura do Spanner dos passos de processamento de longa duração subsequentes.

    • O Spanner também elimina uma sessão se tiver mais de 28 dias. Se estiver a usar a biblioteca de cliente, esta processa automaticamente estes casos. Se não usar uma das bibliotecas de cliente do Spanner, crie uma nova sessão quando este erro ocorrer. Adicione a nova sessão ao conjunto de sessões e remova a sessão eliminada do conjunto.

  • Se usar uma das bibliotecas de cliente do Spanner, a biblioteca gere as sessões automaticamente. Se encontrar este erro, verifique se o seu código não elimina explicitamente as sessões, por exemplo, fechando o cliente da base de dados. Ocasionalmente, isto também pode ser causado por um problema na gestão de sessões da biblioteca cliente.

Recurso esgotado

Os erros RESOURCE_EXHAUSTED: No session available in the pool ou RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session indicam que a sua aplicação não consegue adquirir uma sessão do conjunto de sessões. Isto acontece quando não estão disponíveis sessões para processar novos pedidos de leitura ou escrita.

A tabela seguinte descreve alguns motivos que podem causar estes erros e as ações recomendadas correspondentes.

Motivo Ação recomendada
Todas as sessões no conjunto estão em uso. A sua aplicação pode receber mais pedidos simultâneos do que o número máximo de sessões configurado. Todas as sessões no conjunto estão ocupadas e não existem sessões disponíveis para novos pedidos. Ative as sessões multiplexadas. As sessões multiplexadas permitem que várias transações e leituras partilhem uma única sessão, o que pode reduzir o número total de sessões exigidas pela sua aplicação. Também pode aumentar a configuração de maxSession ou minSession nas definições do conjunto de sessões.
Os pedidos demoram muito tempo a ser concluídos. Os pedidos de leitura ou escrita de longa duração podem ocupar todas as sessões disponíveis durante períodos prolongados. Se estes pedidos demorarem mais tempo do que a definição de limite de tempo de aquisição da sessão, os novos pedidos não podem obter uma sessão do conjunto de sessões. Investigue por que motivo os seus pedidos demoram muito tempo a ser concluídos. Otimize as suas consultas ou lógica de aplicação para reduzir o tempo de execução. Pode aumentar a definição de limite de tempo de obtenção da sessão. Também pode ativar sessões multiplexadas para bibliotecas de cliente elegíveis para melhorar a utilização das sessões.
Existem fugas de sessões. Uma fuga de sessão ocorre quando a sua aplicação extrai uma sessão do conjunto, mas não a devolve após concluir o pedido. Normalmente, isto acontece quando os iteradores ou os conjuntos de resultados não são fechados corretamente no seu código. Se todas as sessões tiverem fugas, não estão disponíveis sessões para novos pedidos. Depure o código da aplicação para identificar e corrigir as fugas de sessão. Certifique-se de que o código fecha corretamente todos os iteradores e conjuntos de resultados. Para mais informações, consulte as Soluções de deteção de fugas de sessões. Também pode usar a funcionalidade limpeza automática de fugas de sessões para definir o seu conjunto de sessões para resolver automaticamente as transações inativas.
A criação de sessões é lenta. A criação de sessões é uma operação computacionalmente dispendiosa. As bibliotecas de cliente enviam APIs BatchCreateSessions para criar sessões iniciais (com base na configuração minSession) e APIs CreateSessions para sessões adicionais (até maxSession). Se a criação de sessões demorar mais do que a definição de tempo limite de aquisição de sessões, os novos pedidos podem atingir o tempo limite enquanto aguardam sessões. Valide a latência das chamadas da API BatchCreateSessions e CreateSessions. A criação lenta de sessões pode resultar de problemas de recursos no lado do Spanner ou de um grande número de operações de criação de sessões em simultâneo.

Erros do mecanismo de controlo do fluxo

O Spanner pode ativar o respetivo mecanismo de controlo de fluxo para se proteger contra sobrecarga nas seguintes condições:

  • Existe uma utilização elevada da CPU no nó do Spanner. Se suspeitar que o seu pedido está a causar uma elevada utilização da CPU, pode usar as métricas de utilização da CPU para investigar o problema.
  • Podem existir pontos críticos que aumentam o tempo de processamento do pedido. Se suspeitar que o seu pedido está a causar pontos críticos, consulte o artigo Encontre pontos críticos na sua base de dados para investigar o problema. Para mais informações, consulte o Key Visualizer.

O mecanismo de controlo de fluxo é suportado pelas seguintes bibliotecas cliente:

O tempo total para a conclusão do pedido não aumenta devido à utilização do mecanismo de controlo de fluxo. Sem este mecanismo, o Spanner aguarda antes de processar o pedido e, eventualmente, devolve um erro DEADLINE_EXCEEDED.

Quando o mecanismo de controlo de fluxo está ativo, o Spanner envia pedidos de volta ao cliente para tentar novamente. Se a nova tentativa consumir o prazo fornecido pelo utilizador na totalidade, o cliente recebe um erro RESOURCE_EXHAUSTED. Este erro é devolvido se o Spanner estimar que o tempo de processamento do pedido é demasiado longo. O erro propaga o controlo de fluxo e o Spanner tenta novamente o pedido ao cliente, em vez de acumular novas tentativas internamente. Isto permite que o Spanner evite a acumulação de consumo de recursos adicional.