Mensagens de erro

Este documento descreve as mensagens de erro que pode encontrar quando trabalha com o BigQuery, incluindo códigos de erro HTTP e passos de resolução de problemas sugeridos.

Para mais informações sobre erros de consulta, consulte o artigo Resolva problemas de erros de consulta.

Para mais informações sobre erros de inserção de streaming, consulte o artigo Resolva problemas de inserções de streaming.

Tabela de erros

As respostas da API BigQuery incluem um código de erro HTTP e um objeto de erro no corpo da resposta. Normalmente, um objeto de erro é um dos seguintes:

A coluna Mensagem de erro na tabela seguinte é mapeada para a propriedade reason num objeto ErrorProto.

A tabela não inclui todos os possíveis erros HTTP nem outros erros de rede. Por conseguinte, não assuma que um objeto de erro está presente em todas as respostas de erro do BigQuery. Além disso, pode receber erros ou objetos de erro diferentes se usar as bibliotecas de cliente da nuvem para a API BigQuery. Para mais informações, consulte as bibliotecas de cliente da API BigQuery.

Se receber um código de resposta HTTP que não aparece na tabela seguinte, o código de resposta indica um problema ou um resultado esperado com o pedido HTTP. Os códigos de resposta no intervalo 5xx indicam um erro do lado do servidor. Se receber um código de resposta 5xx, tente novamente o pedido mais tarde. Em alguns casos, um código de resposta 5xx pode ser devolvido por um servidor intermédio, como um proxy. Examine o corpo da resposta e os cabeçalhos da resposta para ver detalhes sobre o erro. Para ver uma lista completa de códigos de resposta HTTP, consulte o artigo Códigos de resposta HTTP.

Se usar a ferramenta de linhas de comando bq para verificar o estado da tarefa, o objeto de erro não é devolvido por predefinição. Para ver o objeto de erro e a propriedade reason correspondente que é mapeada para a tabela seguinte, use a flag --format=prettyjson. Por exemplo, bq --format=prettyjson show -j *<job id>*. Para ver o registo detalhado da ferramenta bq, use --apilog=stdout. Para saber mais sobre a resolução de problemas da ferramenta bq, consulte o artigo Depuração.

Mensagem de erro Código HTTP Descrição Resolução de problemas
accessDenied 403

Este erro é devolvido quando tenta aceder a um recurso, como um conjunto de dados, tabela, vista ou tarefa, ao qual não tem acesso. Este erro também é devolvido quando tenta modificar um objeto só de leitura.

Contacte o proprietário do recurso e peça acesso ao recurso para o utilizador identificado pelo valor principalEmail no registo de auditoria do erro.
attributeError 400

Este erro é devolvido quando existe um problema com o código do utilizador em que é chamado um atributo de objeto específico, mas este não existe.

Certifique-se de que o objeto com o qual está a trabalhar tem o atributo ao qual está a tentar aceder. Para mais informações sobre este erro, consulte o artigo AttributeError.
backendError 500, 503 ou 504

Este erro indica que o serviço está atualmente indisponível. Isto pode acontecer devido a vários problemas temporários, incluindo:

  • Aumento repentino da procura de serviços: os picos repentinos na procura, como os horários de pico de utilização, podem resultar na redução da carga para proteger a qualidade do serviço para todos os utilizadores do BigQuery. Para evitar que o sistema fique sobrecarregado, o BigQuery pode devolver erros 500 ou 503 para uma pequena parte dos pedidos.
  • Problemas de rede: a natureza distribuída do BigQuery significa que os dados são frequentemente transferidos entre diferentes componentes ou máquinas no sistema. Vários problemas intermitentes de conetividade de rede podem fazer com que o BigQuery devolva um erro 5xx, incluindo falhas de handshake SSL ou outros problemas de infraestrutura de rede entre o utilizador e oGoogle Cloud.
  • Esgotamento de recursos: o BigQuery tem vários limites de recursos internos implementados para proteger o desempenho geral do serviço de um único utilizador ou de uma única tarefa que consuma demasiados recursos. O BigQuery implementa a rejeição de carga para resolver o esgotamento de recursos.
  • Erros de back-end: em casos raros, um problema interno num dos componentes do BigQuery pode resultar num erro 500 ou 503 devolvido ao cliente.

Os erros 5xx são problemas do lado do servidor e o cliente não tem forma de os corrigir nem de os controlar. Do lado do cliente, para mitigar o impacto dos erros 5xx, tem de tentar novamente os pedidos usando rejeições exponenciais truncadas. Para mais informações sobre retiradas exponenciais, consulte Retirada exponencial. No entanto, existem dois casos especiais para resolver problemas deste erro: chamadas jobs.get e chamadas jobs.insert.

jobs.get chamadas

  • Se recebeu um erro 503 ao sondar jobs.get, aguarde alguns segundos e sonde novamente.
  • Se a tarefa for concluída, mas incluir um objeto de erro que contenha backendError, a tarefa falhou. Pode tentar novamente a tarefa em segurança sem preocupações com a consistência dos dados.

jobs.insert chamadas
Se receber este erro ao fazer uma chamada jobs.insert, não é claro se a tarefa foi concluída com êxito. Nesta situação, tem de tentar novamente a tarefa.

Se as novas tentativas não forem eficazes e os problemas persistirem, pode calcular a taxa de pedidos com falhas e contactar o apoio técnico.
Além disso, se observar que um pedido específico ao BigQuery falha persistentemente com um erro 5xx, mesmo quando tenta novamente com recuo exponencial em várias tentativas de reinício do fluxo de trabalho, deve encaminhar esta situação para o apoio técnico para resolver o problema do lado do BigQuery, independentemente da taxa de erro calculada geral. Certifique-se de que comunica claramente o impacto empresarial para que o problema possa ser triado corretamente.
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 numa tabela podem não estar disponíveis para operações DML (DELETE, UPDATE, MERGE), normalmente durante alguns minutos, mas, em casos raros, até 90 minutos. Para mais informações, consulte os artigos Disponibilidade dos dados de streaming e Limitações da DML.

Aguarde alguns minutos e tente novamente ou filtre a declaração para operar apenas em dados mais antigos que estejam fora do buffer de streaming. Para ver se os dados estão disponíveis para operações DML de tabelas, verifique a resposta tables.get para a secção streamingBuffer. Se a secção streamingBuffer estiver ausente, os dados da tabela estão disponíveis para operações DML. Também pode usar o campo streamingBuffer.oldestEntryTime para identificar a antiguidade dos registos no buffer de streaming.

Em alternativa, considere fazer stream de dados com a API BigQuery Storage Write, que não tem esta limitação.
billingNotEnabled 403

Este erro é devolvido quando a faturação não está ativada para o projeto.

Ative a faturação para o projeto na Google Cloud consola.
billingTierLimitExceeded 400

Este erro é devolvido quando o valor de statistics.query.billingTier para uma tarefa a pedido excede 100. Isto ocorre quando as consultas a pedido usam demasiada CPU em relação à quantidade de dados analisados. Para ver instruções sobre como inspecionar os detalhes das tarefas, consulte o artigo Gerir tarefas.

Este erro resulta, na maioria das vezes, da execução de junções cruzadas ineficientes, quer explícita quer implicitamente, por exemplo, devido a uma condição de junção inexata. Estes tipos de consultas não são adequados para preços a pedido devido ao elevado consumo de recursos e, em geral, podem não ser bem dimensionados. Pode otimizar a consulta ou mudar para o modelo de preços com base na capacidade (vagas) para resolver este erro. Para obter informações sobre a otimização de consultas, consulte o artigo Evitar antipadrões de SQL.
bloqueado 403

Este erro é devolvido quando o BigQuery nega temporariamente a operação que tentou realizar, normalmente para evitar uma interrupção do serviço.

Contacte o apoio técnico para mais informações.
duplicado 409

Este erro é devolvido quando tenta criar uma tarefa, um conjunto de dados ou uma tabela que já existe. O erro também é devolvido quando a propriedade writeDisposition de uma tarefa está definida como WRITE_EMPTY e a tabela de destino acedida pela tarefa já existe.

Mude o nome do recurso que está a tentar criar ou altere o valor de writeDisposition na tarefa. Para mais informações, veja como resolver problemas do erro Job already exists.
internalError 500

Este erro é devolvido quando ocorre um erro interno no BigQuery.

Aguarde de acordo com os requisitos de recuo descritos no contrato de nível de serviço do BigQuery e, em seguida, tente novamente a operação. Se o erro continuar a ocorrer, contacte o apoio técnico ou apresente um erro através do Issue Tracker do BigQuery. Também pode reduzir a frequência deste erro usando Reservas.
inválido 400

Este erro é devolvido quando existe qualquer tipo de entrada inválida que não seja uma consulta inválida, como campos obrigatórios em falta ou um esquema de tabela inválido. As consultas inválidas devolvem um erro invalidQuery.
invalidQuery 400

Este erro é devolvido quando tenta executar uma consulta inválida.

Verifique se existem erros de sintaxe na consulta. A referência de consulta contém descrições e exemplos de como criar consultas válidas.
invalidUser 400

Este erro é devolvido quando tenta agendar uma consulta com credenciais de utilizador inválidas.

Atualize as credenciais do utilizador, conforme explicado em Agendar consultas.
jobBackendError 400

Este erro é devolvido quando a tarefa foi criada com êxito, mas falhou devido a um erro interno. Pode ver este erro no jobs.query ou jobs.getQueryResults.

Tente novamente a tarefa com um novo jobId. Se o erro continuar a ocorrer, contacte o apoio técnico.
jobInternalError 400

Este erro é devolvido quando a tarefa foi criada com êxito, mas falhou devido a um erro interno. Pode ver este erro no jobs.query ou jobs.getQueryResults.

Tente novamente a tarefa com um novo jobId. Se o erro continuar a ocorrer, contacte o apoio técnico.
jobRateLimitExceeded 400

Este erro é devolvido quando a tarefa foi criada com êxito, mas falhou com um erro rateLimitExceeded. Pode ver este erro no jobs.query ou no jobs.getQueryResults.

Use a retirada exponencial para reduzir a taxa de pedidos e, em seguida, tente novamente a tarefa com um novo jobId.
notFound 404

Este erro é devolvido quando faz referência a um recurso (um conjunto de dados, uma tabela ou uma tarefa) que não existe ou quando a localização no pedido não corresponde à localização do recurso (por exemplo, a localização em que uma tarefa está a ser executada). Isto também pode ocorrer quando usa decoradores de tabelas para fazer referência a tabelas eliminadas que foram recentemente transmitidas por streaming.

Corrija os nomes dos recursos, especifique corretamente a localização ou aguarde, pelo menos, 6 horas após o streaming antes de consultar uma tabela eliminada.
notImplemented 501

Este erro de tarefa é devolvido quando tenta aceder a uma funcionalidade que não está implementada.

Contacte o apoio técnico para mais informações.
proxyAuthenticationRequired 407

Este erro é devolvido entre o ambiente do cliente e o servidor proxy quando o pedido não tem credenciais de autenticação válidas para o servidor proxy. Para mais informações, consulte o artigo 407 Autenticação proxy necessária.

A resolução de problemas é específica do seu ambiente. Se receber este erro enquanto trabalha em Java, certifique-se de que definiu as propriedades jdk.http.auth.tunneling.disabledSchemes= e jdk.http.auth.proxying.disabledSchemes= sem valor após o sinal de igual.
quotaExceeded 403

Este erro é devolvido quando o seu projeto excede uma quota do BigQuery, uma quota personalizada ou quando não configurou a faturação e excedeu o nível gratuito para consultas.

Veja a propriedade message do objeto de erro para mais informações sobre a quota que foi excedida. Para repor ou aumentar uma quota do BigQuery, contacte o apoio técnico. Para modificar uma quota personalizada, envie um pedido a partir da página Quotas. Se receber este erro ao usar o sandbox do BigQuery, pode atualizar a partir do sandbox.
Para mais informações, consulte o artigo Resolução de problemas de erros de quota do BigQuery.
rateLimitExceeded 403

Este erro é devolvido se o seu projeto exceder um limite de taxa de curto prazo ao enviar demasiados pedidos demasiado rapidamente. Por exemplo, consulte os limites de taxa para tarefas de consulta e os limites de taxa para pedidos API.

Diminua a taxa de pedidos.
Se considerar que o seu projeto não excedeu um destes limites, contacte o apoio técnico.
Para mais informações, consulte o artigo Resolução de problemas de erros de quota do BigQuery.
resourceInUse 400

Este erro é devolvido quando tenta eliminar um conjunto de dados que contém tabelas ou quando tenta eliminar uma tarefa que está atualmente em execução.

Esvazie o conjunto de dados antes de tentar eliminá-lo ou aguarde que uma tarefa seja concluída antes de o eliminar.
resourcesExceeded 400

Este erro é devolvido quando a sua tarefa usa demasiados recursos.

Este erro é devolvido quando a sua tarefa usa demasiados recursos. Para obter informações de resolução de problemas, consulte o artigo Resolva problemas de erros de recursos excedidos.
responseTooLarge 403

Este erro é devolvido quando os resultados da consulta são superiores ao tamanho máximo da resposta. Algumas consultas são executadas em várias fases e este erro é devolvido quando qualquer fase devolve um tamanho de resposta demasiado grande, mesmo que o resultado final seja inferior ao máximo. Este erro é devolvido frequentemente quando as consultas usam uma cláusula ORDER BY.

Por vezes, adicionar uma cláusula LIMIT pode ajudar ou remover a cláusula ORDER BY. Se quiser garantir que podem ser devolvidos resultados grandes, pode definir a propriedade allowLargeResults como true e especificar uma tabela de destino. Para mais informações, consulte o artigo Escrever resultados de consultas grandes.
parado 200

Este código de estado é devolvido quando uma tarefa é cancelada.
tableUnavailable 400

Determinadas tabelas do BigQuery são suportadas por dados geridos por outras equipas de produtos Google. Este erro indica que uma destas tabelas está indisponível.

Quando encontrar esta mensagem de erro, pode tentar novamente o seu pedido (consulte as sugestões de resolução de problemas de internalError) ou contactar a equipa de produtos Google que lhe concedeu acesso aos respetivos dados.
tempo limite excedido 400

O trabalho excedeu o tempo limite.

Considere reduzir a quantidade de trabalho realizado pela sua operação para que possa ser concluído dentro do limite definido. Para mais informações, consulte o artigo Resolva erros de quotas e limites.

Exemplo de resposta de erro

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"
  }
}

Calcule a taxa de pedidos com falhas e o tempo de atividade

A maioria dos erros 500 e 503 pode ser resolvida repetindo a ação com recuo exponencial. No caso de os erros 500 e 503 persistirem, pode calcular a taxa geral de pedidos com falhas e o tempo de atividade correspondente para a comparar com o contrato de nível de serviço (SLA) do BigQuery e determinar se o serviço está a funcionar como esperado.

Para calcular a taxa geral de pedidos com falhas durante os últimos 30 dias, pegue no número de pedidos com falhas para uma chamada ou um método de API específico dos últimos 30 dias e divida-o pelo número total de pedidos para essa chamada ou método de API dos últimos 30 dias. Multiplique este valor por 100 para obter a percentagem média de pedidos com falhas durante 30 dias.

Por exemplo, pode consultar os dados do Cloud Logging para obter o número total de pedidos jobs.insert e o número de pedidos jobs.insert com falhas e fazer o cálculo. Também pode obter os valores da taxa de erro no painel de controlo da API ou através do explorador de métricas no Cloud Monitoring. Estas opções não incluem dados sobre problemas de rede ou encaminhamento encontrados entre o cliente e o BigQuery, pelo que também recomendamos a utilização de um sistema de registo e relatórios do lado do cliente para cálculos mais precisos da taxa de falhas.

Primeiro, subtraia a taxa geral de pedidos com falhas a 100%. Se este valor for igual ou superior ao valor descrito no SLA do BigQuery, o tempo de atividade também cumpre o SLA do BigQuery. No entanto, se este valor for inferior ao valor descrito no SLA, calcule o tempo de atividade manualmente.

Para calcular o tempo de atividade, tem de saber o número de minutos que são considerados tempo de inatividade do serviço. Tempo de inatividade do serviço significa um período de um minuto com uma taxa de erros superior a 10%, calculada de acordo com as definições do SLA. Para calcular o tempo de atividade, pegue no total de minutos dos últimos 30 dias e subtraia o total de minutos em que o serviço esteve indisponível. Divida o tempo restante pelo total de minutos dos últimos 30 dias e multiplique este valor por 100 para obter a percentagem de tempo de atividade durante 30 dias. Para mais informações sobre as definições e os cálculos relacionados com o SLA , consulte o contrato de nível de serviço (SLA) do BigQuery

Se a percentagem de tempo de atividade mensal for superior ou igual ao valor descrito no SLA do BigQuery, é muito provável que o erro tenha sido causado por um problema transitório. Por isso, pode continuar a tentar novamente com recuo exponencial.

Se o tempo de atividade for inferior ao valor apresentado no SLA, contacte o apoio técnico para obter ajuda e partilhe a taxa de erro geral observada e os cálculos do tempo de atividade.

Erros de autenticação

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

{"error" : "_description_string_"}

O erro é acompanhado de um erro de pedido incorreto HTTP 400 ou de um erro não autorizado HTTP 401. _description_string_ é um dos códigos de erro definidos pela especificação OAuth2. Por exemplo:

{"error":"invalid_client"}

Reveja os erros

Pode usar o explorador de registos para ver erros de autenticação para tarefas, utilizadores ou outros âmbitos específicos. Seguem-se exemplos de filtros do Explorador de registos que pode usar para rever erros de autenticação:

  • Pesquise tarefas com falhas e problemas de autorização nos registos de auditoria de políticas recusadas:

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

    Substitua PROJECT_ID pelo ID do projeto que contém o recurso.

  • Pesquise um utilizador ou uma conta de serviço específica usada para autenticação:

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

    Substitua EMAIL pelo endereço de email do utilizador ou da conta de serviço.

  • Pesquise alterações às políticas de gestão de identidade e de acesso nos registos de auditoria da atividade do administrador:

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

  • Pesquise alterações a um conjunto de dados específico do BigQuery nos registos de auditoria de acesso aos dados:

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

    Substitua DATASET_ID pelo ID do conjunto de dados que contém o recurso.

Mensagens de erro de conetividade

A tabela seguinte apresenta mensagens de erro que pode ver devido a problemas de conetividade intermitentes quando usa as bibliotecas cliente ou chama a API BigQuery a partir do seu código:

Mensagem de erro Biblioteca cliente ou API Resolução de problemas
com.google.cloud.bigquery.BigQueryException: Read timed out Java Defina um valor de limite de tempo maior.
A ligação foi encerrada: javax.net.ssl.SSLException: java.net.SocketException: Connection reset at com.google.cloud.bigquery.spi.v2.HttpBigQueryRpc.translate(HttpBigQueryRpc.java:115) Java Implemente um mecanismo de repetição e defina um valor de tempo limite maior.
javax.net.ssl.SSLHandshakeException: O anfitrião remoto terminou o handshake Java Implemente um mecanismo de repetição e defina um valor de tempo limite maior.
BrokenPipeError: [Errno 32] Broken pipe Python Implemente um mecanismo de nova tentativa. Para mais informações sobre este erro, consulte o artigo BrokenPipeError.
Ligação anulada. RemoteDisconnected('Remote end closed connection without response' Python Defina um valor de limite de tempo maior.
SSLEOFError (EOF occurred in violation of protocol) Python Este erro é devolvido em vez de um erro HTTP 413 (ENTITY_TOO_LARGE). Reduza o tamanho do pedido.
TaskCanceledException: uma tarefa foi cancelada Biblioteca .NET Aumente o valor do tempo limite no lado do cliente.
google.api_core.exceptions.PreconditionFailed: 412 PATCH Python Este erro é devolvido ao tentar atualizar um recurso de tabela através de um pedido HTTP. Certifique-se de que o ETag no cabeçalho HTTP não está desatualizado. Para operações ao nível da tabela ou do conjunto de dados, certifique-se de que o recurso não foi alterado desde a última vez que foi instanciado e recrie o objeto, se necessário.
Falha ao estabelecer uma nova ligação: [Errno 110] Connection timed out Bibliotecas cliente Este erro é devolvido quando este pedido atingiu o fim do ficheiro (EOF) durante a transmissão em fluxo ou a leitura de dados do BigQuery. Implemente um mecanismo de repetição e defina um valor de tempo limite maior.
socks.ProxyConnectionError: Error connecting to HTTP proxy :8080: [Errno 110] Connection timed out Bibliotecas cliente Resolva problemas com o estado e as definições de proxy. Implemente um mecanismo de repetição e defina um valor de tempo limite maior.
Recebeu um EOF inesperado ou 0 bytes do fluxo de transporte Bibliotecas cliente Implemente um mecanismo de repetição e defina um valor de tempo limite maior.

Google Cloud mensagens de erro da consola

A tabela seguinte apresenta mensagens de erro que pode ver enquanto trabalha na Google Cloud consola.

Mensagem de erro Descrição Resolução de problemas
Resposta de erro desconhecida do servidor. Este erro é apresentado quando a consola Google Cloud recebe um erro desconhecido do servidor; por exemplo, quando clica num conjunto de dados ou noutro tipo de link e a página não pode ser apresentada. Mude para o modo de navegação anónima ou privada do navegador e repita a ação que resultou no erro. Se não ocorrer nenhum erro no modo de navegação anónima, o erro pode dever-se a uma extensão do navegador, como um bloqueador de anúncios. Desative as extensões do navegador quando não estiver no modo de navegação anónima e verifique se isso resolve o problema.