Mensagens de erro

Neste documento, descrevemos as mensagens de erro que podem ser encontrados ao trabalhar com o BigQuery, incluindo códigos de erro HTTP e etapas de solução de problemas sugeridas.

Saiba mais sobre erros de consulta em Corrigir erros de consulta.

Para saber mais sobre erros de inserção por streaming, consulte Resolver problemas de inserções por streaming.

Tabela de erros

As respostas da API do BigQuery incluem um código do erro HTTP e um objeto de erros no corpo da resposta. Um objeto de erro geralmente é um dos seguintes:

Um objeto errors, que contém uma matriz de objetos ErrorProto.
Um objeto errorResults, que contém um único objeto ErrorProto.

A coluna Mensagem de erro na tabela a seguir é mapeada para a propriedade reason em um objeto ErrorProto.

Essa tabela não inclui todos os erros HTTP possíveis ou outros erros de rede. Portanto, não presuma que um erro de objeto esteja presente em todas as respostas de erro do BigQuery. Além disso, você poderá receber erros ou objetos de erro diferentes se usar as bibliotecas de cliente do Cloud para a API do BigQuery. Para mais informações, consulte Bibliotecas de cliente da API BigQuery.

Quando você recebe um código de resposta HTTP que não aparece na tabela abaixo, o código de resposta indica um problema ou um resultado esperado com a solicitação HTTP. Os códigos de resposta no intervalo 5xx indicam um erro do lado do servidor. Se você receber um código de resposta 5xx, tente fazer a solicitação novamente mais tarde. Em alguns casos, um código de resposta 5xx pode ser retornado por um servidor intermediário, como um proxy. Examine o corpo da resposta e os cabeçalhos das respostas para saber mais sobre o erro. Para conferir a lista completa de códigos de resposta HTTP, consulte códigos de resposta HTTP.

Se você usar a ferramenta de linha de comando bq para consultar o status do job, o objeto de erro não será retornado por padrão. Para visualizar o objeto de erro e a propriedade reason correspondente que é mapeada para a tabela a seguir, use a sinalização --format=prettyjson. Por exemplo, bq --format=prettyjson show -j <job id>. Para visualizar o registro detalhado da ferramenta bq, use --apilog=stdout. Para saber mais sobre como solucionar problemas da ferramenta bq, consulte Depuração.

Mensagem de erro	Código HTTP	Descrição	Solução de problemas
accessDenied	403	Esse erro é retornado quando você tenta acessar um recurso, como um conjunto de dados, tabela, visualização ou job, a que não tem acesso. Ele também é retornado quando você tenta modificar um objeto somente leitura.	Entre em contato com o proprietário do recurso e solicite acesso ao recurso do usuário identificado pelo valor `principalEmail` no registro de auditoria do erro.
backendError	500 ou 503	Este erro é retornado quando há uma falha temporária no servidor, como problema de conexão de rede ou sobrecarga no servidor.	Em geral, aguarde alguns segundos e tente novamente. Se o problema se repetir, tente de novo com espera exponencial. No entanto, há dois casos especiais para solucionar o problema desse erro: chamadas `jobs.get` e `jobs.insert`. `jobs.get` chamadas Caso tenha recebido o erro 503 ao pesquisar `jobs.get`, aguarde alguns segundos e tente novamente. Se o job é concluído, mas inclui um objeto de erro que contém `backendError`, significa que ele falhou. É possível repeti-lo seguramente sem se preocupar com a consistência de dados. `jobs.insert` chamadas Se você receber esse erro ao fazer uma chamada `jobs.insert`, não ficará claro se o job foi bem-sucedido. Nesta situação, você precisa repeti-lo.
badRequest	400	O erro `'UPDATE or DELETE statement over table <project.dataset.table> would affect rows in the streaming buffer, which is not supported'` pode ocorrer quando algumas linhas transmitidas recentemente em uma tabela podem não estar disponíveis para operações DML (`DELETE`, `UPDATE`, `MERGE`), normalmente por algumas minutos, mas, em casos raros, até 90 minutos. Para mais informações, consulte Disponibilidade de dados de streaming e Limitações do DML.	Para ver se os dados estão disponíveis para operações DML de tabela, verifique a resposta `tables.get` para a seção streamingBuffer. Se a seção streamingBuffer estiver ausente, os dados da tabela estarão disponíveis para operações DML. Também é possível usar o campo `streamingBuffer.oldestEntryTime` para identificar a idade dos registros no buffer de streaming.
billingNotEnabled	403	Este erro é retornado quando o faturamento não está ativado no projeto.	Ative o faturamento para o projeto no Console do Google Cloud.
billingTierLimitExceeded	400	Este erro é retornado quando o valor de `statistics.query.billingTier` de um job sob demanda excede 100. Isso ocorre quando as consultas sob demanda usam muita CPU em relação à quantidade de dados verificados. Para instruções sobre como inspecionar estatísticas de jobs, consulte Como gerenciar jobs.	Na maioria das vezes, esse erro resulta da execução de correlações ineficientes, explícita ou implicitamente, por exemplo, devido a uma condição de junção inexata. Esses tipos de consultas não são adequados para preços sob demanda devido ao alto consumo de recursos e, em geral, podem não ser bem dimensionados. É possível otimizar a consulta ou mudar para usar a baseado na capacidade (slots) para resolver esse erro. Para mais informações sobre como otimizar consultas, acesse Como evitar antipadrões do SQL.
bloqueado	403	Este erro é retornado quando o BigQuery coloca temporariamente a operação que você tentou executar na lista de bloqueio, geralmente para evitar interrupção do serviço.	Entre em contato com o suporte para mais informações.
duplicar	409	Este erro é retornado ao tentar criar um job, um conjunto de dados ou uma tabela que já existe. O erro também retorna quando a property `writeDisposition` de um job é definida como `WRITE_EMPTY` e a tabela de destino acessada pelo job já existe.	Renomeie o recurso que você está tentando criar ou altere o valor `writeDisposition` no job.
internalError	500	Este erro é retornado quando ocorre um erro interno no BigQuery.	Aguarde de acordo com os requisitos de retirada descritos no Contrato de nível de serviço do BigQuery, depois tente a operação novamente. Se o erro persistir, entre em contato com o suporte ou registre um bug usando o rastreador de problemas do BigQuery. Também é possível reduzir a frequência desse erro usando Reservas.
inválido	400	Este erro é retornado quando há algum tipo de entrada inválida que não seja uma consulta, como campos obrigatórios ausentes ou esquema de tabela inválido. Consultas inválidas retornam um erro `invalidQuery`.
invalidQuery	400	Este erro é retornado quando você tenta executar uma consulta inválida.	Verifique se há erros de sintaxe na sua consulta. A referência de consulta contém descrições e exemplos de como criar consultas válidas.
invalidUser	400	Esse erro é retornado quando você tenta programar uma consulta com credenciais de usuário inválidas.	Atualize as credenciais do usuário, conforme explicado em Como programar consultas.
jobBackendError	400	Este erro é retornado quando o job é criado, mas falha com um erro interno. É possível ver esse erro em `jobs.query` ou `jobs.getQueryResults`.	Tente novamente com um novo `jobId`. Se o erro persistir, entre em contato com o suporte.
jobInternalError	400	Este erro é retornado quando o job é criado, mas falha com um erro interno. É possível ver esse erro em `jobs.query` ou `jobs.getQueryResults`.	Tente novamente com um novo `jobId`. Se o erro persistir, entre em contato com o suporte.
notFound	404	Este erro é aparece quando você se refere a um recurso (um conjunto de dados, uma tabela ou um job) que não existe ou quando o local na solicitação não corresponde ao local do recurso (por exemplo, o local em que um job está sendo executado). Isso também pode ocorrer ao usar decoradores de tabela para se referir às tabelas excluídas que receberam streaming recentemente.	Corrija os nomes dos recursos, especifique corretamente o local ou aguarde pelo menos seis horas após o streaming antes de consultar uma tabela excluída.
notImplemented	501	Este erro de job é retornado quando você tenta acessar um recurso que não foi implementado.	Entre em contato com o suporte para mais informações.
quotaExceeded	403	Este erro é retornado quando seu projeto excede uma cota do BigQuery ou uma cota personalizada, ou até mesmo quando o faturamento não foi configurado e excede o nível gratuito para consultas.	Visualize a property `message` do objeto de erro para saber mais sobre qual cota foi excedida. Para redefinir ou aumentar uma cota do BigQuery, entre em contato com o suporte. Para modificar uma cota personalizada, envie uma solicitação por meio da página do Console do Google Cloud. Se você receber esse erro usando o sandbox do BigQuery, poderá fazer upgrade do sandbox. Para mais informações, consulte Como solucionar problemas de erros de cota do BigQuery.
rateLimitExceeded	403	Este erro é retornado quando o projeto excede um limite de taxa de curto prazo enviando várias solicitações muito rapidamente. Por exemplo, consulte os limites de taxa para jobs de consulta e os limites de taxa para solicitações de API.	Reduza a taxa de solicitação. Se você acredita que o projeto não excedeu nenhum desses limites, entre em contato com o suporte. Para mais informações, consulte Como solucionar problemas de erros de cota do BigQuery.
resourceInUse	400	Este erro é retornado quando você tenta excluir um conjunto de dados com tabelas ou um job que esteja em execução.	Esvazie o conjunto de dados ou aguarde a conclusão do job antes de tentar excluí-lo.
resourcesExceeded	400	Este erro é retornado quando o job usa um número excessivo de recursos.	Este erro é retornado quando o job usa um número excessivo de recursos. Para informações sobre solução de problemas, consulte Corrigir erros de recursos excedidos.
responseTooLarge	403	Este erro é retornado quando os resultados da consulta são maiores do que o tamanho máximo da resposta. Algumas consultas são executadas em vários cenários, e este erro é retornado quando qualquer cenário apresenta uma resposta muito grande, mesmo que o resultado final seja menor do que o máximo. Esse erro normalmente retorna quando consultas usam uma cláusula `ORDER BY`.	Adicionar uma cláusula `LIMIT` ou remover a cláusula `ORDER BY` às vezes pode ser útil. Para garantir que resultados grandes retornem, defina a property `allowLargeResults` como `true` e especifique uma tabela de destino. Para mais informações, consulte Como gravar resultados de consulta extensos.
interrompido	200	Este código de status é retornado quando um job é cancelado.
tableUnavailable	400	Algumas tabelas do BigQuery têm como base dados gerenciados por outras equipes de produto do Google. Este erro indica que uma dessas tabelas está indisponível.	Ao encontrar essa mensagem de erro, é possível repetir a solicitação (consulte as sugestões de solução de problemas em internalError) ou entrar em contato com a equipe de produto do Google que lhe concedeu acesso aos dados.
timeout	400	O tempo limite do job expirou.	Reduza a quantidade de trabalho realizada pela sua operação para que ela seja concluída dentro do limite definido. Consulte Cotas e limites.

Resposta de erro de amostra

GET https://bigquery.googleapis.com/bigquery/v2/projects/12345/datasets/foo
Response:
[404]
{
  "error": {
  "errors": [
  {
    "domain": "global",
    "reason": "notFound",
    "message": "Not Found: Dataset myproject:foo"
  }],
  "code": 404,
  "message": "Not Found: Dataset myproject:foo"
  }
}

Erros de autenticação

Os erros emitidos pelo sistema de geração de tokens OAuth retornam o seguinte objeto JSON, conforme definido pela especificação OAuth2.

{"error" : "description_string"}

O erro vem acompanhado de outro erro, seja "HTTP 400 Solicitação inválida" ou "HTTP 401 Não autorizado". description_string é um dos códigos de erro definidos pela especificação OAuth2. Por exemplo:

{"error":"invalid_client"}

Analisar erros

Use o Explorador de registros para conferir erros de autenticação de jobs, usuários ou outros escopos específicos. Confira abaixo vários exemplos de filtros do Logs Explorer que podem ser usados para analisar erros de autenticação.

Pesquise jobs com falhas e problemas de permissão nos registros de auditoria de política negada:

    resource.type="bigquery_resource"
    protoPayload.status.message=~"Access Denied"
    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"

Pesquise um usuário ou uma conta de serviço específicos usados para autenticação:

    resource.type="bigquery_resource"
    protoPayload.authenticationInfo.principalEmail="EMAIL"

Substitua EMAIL pelo endereço de e-mail do usuário ou da conta de serviço.

Pesquise mudanças na política do IAM nos registros de auditoria de atividade do administrador:

    protoPayload.methodName=~"SetIamPolicy"
    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"

Pesquise mudanças em um conjunto de dados específico do BigQuery nos registros de auditoria de acesso a dados:

    resource.type="bigquery_resource"
    protoPayload.resourceName="projects/PROJECT_ID/datasets/DATASET_ID"
    logName=projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access

Substitua:

PROJECT_ID: o ID do projeto que contém o recurso
DATASET_ID: o ID do projeto que contém o recurso

Mensagens de erro de conectividade

A tabela a seguir lista mensagens de erro que podem ser exibidas devido a problemas de conectividade intermitente ao usar as bibliotecas de cliente ou chamar a API BigQuery pelo código:

Mensagem de erro	Biblioteca de cliente ou API	Solução de problemas
A conexão foi encerrada: javax.net.ssl.SSLException: java.net.SocketException: Conexão redefinida em com.google.cloud.bigquery.spi.v2.HttpBigQueryRpc.translate(HttpBigQueryRpc.java:115)	Java	Implementar um mecanismo de repetição e definir um valor de tempo limite maior.
javax.net.ssl.SSLHandshakeException: o host remoto encerrou o handshake	Java	Implementar um mecanismo de repetição e definir um valor de tempo limite maior.
Conexão cancelada. RemoteDisconnected('Remote end closed connection without response'	Python	Defina um valor de tempo limite maior.
TaskCanceledException: uma tarefa foi cancelada.	Biblioteca .NET	Aumente o valor do tempo limite no lado do cliente.

Mensagens de erro do console do Google Cloud

A tabela a seguir lista mensagens de erro que podem aparecer enquanto você trabalha no console do Google Cloud.

Mensagem de erro	Descrição	Solução de problemas
Resposta de erro desconhecida do servidor.	Esse erro é exibido quando o console do Google Cloud recebe um erro desconhecido do servidor. Por exemplo, quando você clica em um conjunto de dados ou outro tipo de link, e a página não pode ser exibida.	Alterne para o modo de navegação anônima ou privada do navegador e repita a ação que resultou no erro. Se nenhum erro resultar no modo de navegação anônima, ele pode ocorrer devido a uma extensão do navegador, como um bloqueador de anúncios. Desative as extensões do navegador enquanto não estiver no modo de navegação anônima e verifique se isso resolve o problema.