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:

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.
attributeError 400 Esse erro é retornado quando há um problema com o código do usuário em que um determinado atributo de objeto é chamado, mas não existe. Verifique se o objeto com que você está trabalhando tem o atributo que você está tentando acessar. Para mais informações sobre esse erro, consulte AttributeError.
backendError 500, 503 ou 504

Esse erro indica que o serviço não está disponível no momento. Isso pode acontecer devido a vários problemas temporários, incluindo:

  • Aumento repentino na demanda de serviço: picos repentinos na demanda, como horários de pico de uso, podem resultar em redução de carga para proteger a qualidade do serviço para todos os usuários do BigQuery. Para evitar que o sistema fique sobrecarregado, o BigQuery pode retornar erros 500 ou 503 para uma pequena parte das solicitações.
  • Problemas de rede: a natureza distribuída do BigQuery significa que os dados são transferidos entre diferentes componentes ou máquinas no sistema. Vários problemas intermitentes de conectividade de rede podem fazer com que o BigQuery retorne um erro 5xx, incluindo falhas de handshake de SSL ou outros problemas de infraestrutura de rede entre o usuário e Trusted Cloud by S3NS.
  • Esgotamento de recursos: o BigQuery tem vários limites internos de recursos para proteger o desempenho geral do serviço contra um único usuário ou job que consuma muitos recursos. O BigQuery implementa o corte de carga para lidar com o esgotamento de recursos.
  • Erros de back-end: em casos raros, um problema interno em um dos componentes do BigQuery pode resultar em um erro 500 ou 503 retornado ao cliente.
 Os erros 5xx são problemas do lado do serviço, e o cliente não tem como corrigir ou controlar esses erros. Do lado do cliente, para reduzir o impacto dos erros 5xx, repita as solicitações usando esperas exponenciais truncadas. Para mais informações sobre esperas exponenciais, consulte 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.

Se as novas tentativas não forem eficazes e os problemas persistirem, calcule a taxa de solicitações com falha e entre em contato com o suporte.

Além disso, se você observar que uma solicitação específica ao BigQuery falha persistentemente com um erro 5xx, mesmo quando repetida usando espera exponencial em várias tentativas de reinicialização do fluxo de trabalho, encaminhe o problema ao suporte para resolver o problema do lado do BigQuery, independente da taxa de erro geral calculada. Comunique claramente o impacto nos negócios para que o problema seja avaliado 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 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 doTrusted 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 detalhes 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.
jobRateLimitExceeded 400 Esse erro é retornado quando o job é criado, mas falha com um erro rateLimitExceeded. É possível ver esse erro em jobs.query ou jobs.getQueryResults. Use a espera exponencial para reduzir a taxa de solicitação e tente novamente o job com um novo jobId.
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.
proxyAuthenticationRequired 407 Esse erro é retornado entre o ambiente do cliente e o servidor proxy quando a solicitação não tem credenciais de autenticação válidas para o servidor proxy. Para mais informações, consulte 407 Autenticação de proxy necessária. A solução de problemas é específica para seu ambiente. Se você receber esse erro ao trabalhar em Java, verifique se 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 é 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 na página do console doTrusted 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. Para mais informações, consulte 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"
  }
}

Calcular a taxa de solicitações com falha e o tempo de atividade

A maioria dos erros 500 e 503 pode ser resolvida repetindo a ação com espera exponencial. Se os erros 500 e 503 persistirem, calcule a taxa geral de solicitações com falha e o tempo de atividade correspondente para comparar com o Contrato de nível de serviço (SLA) do BigQuery e determinar se o serviço está funcionando como esperado.

Para calcular a taxa geral de solicitações com falha nos últimos 30 dias, divida o número de solicitações com falha de uma chamada ou método de API específico nos últimos 30 dias pelo número total de solicitações dessa chamada ou método de API nos últimos 30 dias. Multiplique esse valor por 100 para saber a porcentagem média de solicitações com falha em 30 dias.

Por exemplo, é possível consultar os dados do Cloud Logging para saber o número total de solicitações jobs.insert e o número de solicitações jobs.insert com falha e fazer o cálculo. Também é possível extrair os valores da taxa de erros do painel de APIs ou usando o Metrics Explorer no Cloud Monitoring. Essas opções não incluem dados sobre problemas de rede ou roteamento encontrados entre o cliente e o BigQuery. Por isso, também recomendamos usar um sistema de geração de relatórios e registros do lado do cliente para cálculos mais precisos da taxa de falha.

Primeiro, pegue 100% menos a taxa geral de solicitações com falha. Se esse valor for maior ou igual ao descrito no SLA do BigQuery, o tempo de atividade também atenderá ao SLA do BigQuery. No entanto, se esse valor for menor que o descrito no SLA, calcule o tempo de atividade manualmente.

Para calcular o tempo de atividade, você precisa saber o número de minutos considerados como inatividade do serviço. Inatividade do serviço significa um período de um minuto com uma taxa de erro superior a 10%, calculada de acordo com as definições do SLA. Para calcular o tempo de atividade, pegue o total de minutos dos últimos 30 dias e subtraia o total de minutos em que o serviço ficou inativo. Divida o tempo restante pelo total de minutos dos últimos 30 dias e multiplique esse valor por 100 para saber a porcentagem de tempo de atividade em 30 dias. Para mais informações sobre as definições e cálculos relacionados ao SLA , consulte o Contrato de nível de serviço (SLA) do BigQuery.

Se a porcentagem mensal de tempo de atividade for maior ou igual ao valor descrito no SLA do BigQuery, o erro provavelmente foi causado por um problema temporário. Portanto, continue tentando usar o backoff exponencial.

Se o tempo de atividade estiver abaixo do valor apresentado no SLA, entre em contato com o suporte para receber ajuda e compartilhe a taxa geral de erros observada e os cálculos de tempo de atividade.

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
com.google.cloud.bigquery.BigQueryException: Read timed out Java Defina um valor de tempo limite maior.
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 Implemente um mecanismo de repetição e defina um valor de tempo limite maior.
javax.net.ssl.SSLHandshakeException: o host remoto encerrou 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 repetição. Para mais informações sobre esse erro, consulte BrokenPipeError.
Conexão cancelada. RemoteDisconnected('Remote end closed connection without response' Python Defina um valor de tempo limite maior.
SSLEOFError (EOF ocorreu em violação do protocolo) Python Esse erro é retornado em vez de um erro HTTP 413 (ENTITY_TOO_LARGE). Reduza o tamanho da solicitação.
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 Esse erro é retornado ao tentar atualizar um recurso de tabela usando uma solicitação HTTP. Verifique se a ETag no cabeçalho HTTP não está desatualizada. Para operações no nível da tabela ou do conjunto de dados, verifique se o recurso não mudou desde a última vez que foi instanciado e recrie o objeto, se necessário.
Falha ao estabelecer uma nova conexão: [Errno 110] Connection timed out Bibliotecas de cliente Esse erro é retornado quando a solicitação atinge o fim do arquivo (EOF) ao fazer streaming ou ler dados do BigQuery. Implemente um mecanismo de repetição e defina um valor de tempo limite maior.
socks.ProxyConnectionError: Error connecting to HTTP proxy xxx.xx.xxx.xx:8080: [Errno 110] Connection timed out Bibliotecas de cliente Resolva problemas de status e configuraçõ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 stream de transporte Bibliotecas de cliente Implemente um mecanismo de repetição e defina um valor de tempo limite maior.

Trusted Cloud mensagens de erro do console

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

Mensagem de erro Descrição Solução de problemas
Resposta de erro desconhecida do servidor. Esse erro é exibido quando o console do Trusted 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.