Códigos de erro do Spanner

Nesta página, descrevemos os códigos de erro do Spanner e as ações recomendadas para tratar 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 a falha de maneira genérica, bem como uma resposta que fornece informações mais específicas sobre o erro que causou 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, 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, 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 que corresponda ao tempo real em que uma resposta é útil. Para operações que mudam o estado do sistema, um erro pode ser retornado mesmo que a operação tenha sido concluída com sucesso.

Para dicas, consulte Resolver erros de prazo excedido.
FAILED_PRECONDITION A operação foi rejeitada porque uma condição prévia 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, ler ou consultar um carimbo de data/hora que excedeu a Inatividade máxima do carimbo de data/hora. 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 de novo, 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 a atualização de uma entidade ou a 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 Algum recurso foi esgotado.

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

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

Para mais informações, consulte também Códigos de erro relacionados à sessão.		 Para o plano de administrador, verifique se você não excedeu a cota do Spanner ou do projeto. Se você excedeu uma cota, peça um aumento ou aguarde a redefinição antes de tentar de novo. Configure as novas tentativas para usar espera exponencial.

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

Em geral, se o aplicativo estiver apresentando erros RESOURCE_EXHAUSTED, trate a situação como um erro UNAVAILABLE e tente de novo com 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 está indisponí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 neste erro. Verifique se a solicitação é segura. Em seguida, tente de novo com espera exponencial.

Erros de sessão

O Spanner usa sessões para gerenciar interações entre o aplicativo e o banco de dados. As sessões representam uma conexão com o banco de dados e facilitam operações como leituras e gravações.

Erros comuns relacionados à sessão que seu aplicativo pode encontrar incluem:

Sessão não encontrada

O erro Session not found ocorre quando o aplicativo tenta usar uma sessão que não existe mais. Esse problema pode ocorrer por vários motivos.

  • Seu aplicativo cliente pode excluir uma sessão explicitamente. Por exemplo, fechar um cliente de banco de dados no código ou chamar a API deleteSessions diretamente remove a sessão. Se você não usa uma das bibliotecas de cliente do Spanner, crie uma sessão quando esse erro ocorrer. Adicione a nova sessão ao pool e remova a sessão excluída dele.

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

    • Ela exclui uma sessão se ela ficar inativa por mais de uma hora. Isso pode acontecer em jobs de fluxo de dados em que o processamento downstream leva mais tempo do que o tempo limite de inatividade da sessão. Se você estiver usando um job do Dataflow, adicione uma operação de transformação Reshuffle após a leitura do Spanner no pipeline do Dataflow. Isso pode ajudar a desacoplar a operação de leitura do Spanner das etapas de processamento de longa duração subsequentes.

    • O Spanner também exclui uma sessão se ela tiver mais de 28 dias. Se você estiver usando a biblioteca de cliente, ela vai processar esses casos automaticamente. Se você não usar uma das bibliotecas de cliente do Spanner, crie uma nova sessão quando esse erro ocorrer. Adicione a nova sessão ao pool e remova a sessão excluída dele.

  • Se você usa uma das bibliotecas de cliente do Spanner, a biblioteca gerencia sessões automaticamente. Se você encontrar esse erro, verifique se o código não exclui sessões explicitamente, como ao fechar o cliente do banco de dados. Às vezes, isso também pode ser causado por um problema no gerenciamento de sessões da biblioteca de 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 o aplicativo não consegue adquirir uma sessão do pool de sessões. Isso acontece quando não há sessões disponíveis para processar novas solicitações de leitura ou gravação.

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

Motivo Ação recomendada
Todas as sessões no pool estão em uso. Seu aplicativo pode receber mais solicitações simultâneas do que o número máximo configurado de sessões. Todas as sessões no pool estão ocupadas, sem sessões disponíveis para novas solicitações. Ative as sessões multiplexadas. As sessões multiplexadas permitem que várias transações e leituras compartilhem uma única sessão, o que pode reduzir o número total de sessões necessárias para seu aplicativo. Você também pode aumentar a configuração de maxSession ou minSession nas configurações do pool de sessões.
As solicitações levam muito tempo para serem concluídas. Solicitações de leitura ou gravação de longa duração podem ocupar todas as sessões disponíveis por períodos prolongados. Se essas solicitações demorarem mais do que a configuração de tempo limite de aquisição da sessão, novas solicitações não poderão obter uma sessão do pool de sessões. Investigue por que suas solicitações demoram muito para serem concluídas. Otimize suas consultas ou a lógica do aplicativo para reduzir o tempo de execução. É possível aumentar a configuração de tempo limite de aquisição de sessão. Também é possível ativar sessões multiplexadas para bibliotecas de cliente qualificadas e melhorar a utilização da sessão.
Há vazamentos de sessão. Um vazamento de sessão ocorre quando o aplicativo faz o check-out de uma sessão do pool, mas não a retorna após concluir a solicitação. Isso geralmente acontece quando iteradores ou conjuntos de resultados não são fechados corretamente no seu código. Se todas as sessões vazarem, nenhuma estará disponível para novas solicitações. Depure o código do aplicativo para identificar e corrigir os vazamentos de sessão. Verifique se o código fecha corretamente todos os iteradores e conjuntos de resultados. Para mais informações, consulte Soluções de detecção de vazamento de sessão. Você também pode usar o recurso de limpeza automática de vazamentos de sessão para definir que o pool de sessões resolva automaticamente transações inativas.
A criação de sessões está lenta. A criação de sessões é uma operação computacionalmente cara. 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é o maxSession). Se a criação da sessão levar mais tempo do que a configuração de tempo limite de aquisição da sessão, novas solicitações poderão atingir o tempo limite enquanto aguardam sessões. Verifique a latência das chamadas de 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 simultâneas de criação de sessões.

Erros no mecanismo de controle de fluxo

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

  • Há um alto uso da CPU no nó do Spanner. Se você suspeitar que a solicitação está causando alto uso da CPU, use as métricas de utilização da CPU para investigar o problema.
  • Pode haver pontos de acesso, o que aumenta o tempo de processamento da solicitação. Se você suspeitar que sua solicitação está causando pontos de acesso, consulte Encontrar pontos de acesso no seu banco de dados para investigar o problema. Para mais informações, consulte Key Visualizer.

O mecanismo de controle de fluxo é compatível com as seguintes bibliotecas de cliente:

O tempo total para a conclusão da solicitação não vai aumentar devido ao uso do mecanismo de controle de fluxo. Sem esse mecanismo, o Spanner aguarda antes de processar a solicitação e, eventualmente, retorna um erro DEADLINE_EXCEEDED.

Quando o mecanismo de controle de fluxo está ativo, o Spanner envia solicitações de volta ao cliente para tentar de novo. Se a nova tentativa consumir todo o prazo fornecido pelo usuário, o cliente vai receber um erro RESOURCE_EXHAUSTED. Esse erro é retornado se o Spanner estimar que o tempo de processamento da solicitação é muito longo. O erro propaga o controle de fluxo, e o Spanner repete a solicitação para o cliente em vez de acumular novas tentativas internamente. Isso permite que o Spanner evite o acúmulo de consumo de recursos adicionais.