Códigos de erro do Spanner

Esta página descreve os códigos de erro do Spanner e as ações recomendadas para processar 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 junto 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 forma 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, a inserção de 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. Para operações que alteram o estado do sistema, um erro pode ser retornado mesmo que a operação tenha sido concluída.

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, a leitura ou consulta de um carimbo de data/hora que excedeu a inatividade máxima. 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 e a causa específica 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 Houve o esgotamento de algum recurso.

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

No plano de dados, isso pode acontecer se os nós do Spanner estiverem sobrecarregados.		 No plano de administrador, verifique se você não excedeu a cota do Spanner ou do projeto. Se você tiver excedido uma cota, solicite um aumento ou aguarde a redefinição antes de tentar novamente. Configure as novas tentativas para usar a espera exponencial.

Para o plano de dados, verifique se os nós do Spanner não excederam a capacidade. O Spanner tenta executar essas ações novamente na biblioteca de cliente. Se todas as novas tentativas falharem, consulte Erros no mecanismo de controle de fluxo.

Em geral, se o aplicativo apresentar erros RESOURCE_EXHAUSTED, trate a situação como um erro UNAVAILABLE e tente novamente 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. 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 a espera exponencial.

Erros no mecanismo de controle de fluxo

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

O mecanismo de controle de fluxo tem suporte das seguintes bibliotecas de cliente:

O tempo geral 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 que ele tente novamente. 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 tenta novamente a solicitação ao cliente, em vez de acumular novas tentativas internamente. Isso permite que o Spanner evite acumular o consumo de recursos.