Mensagens de erro

Você encontrará dois tipos de erros ao trabalhar com o BigQuery: códigos dos erros HTTP ou erros de job. Os erros de job são representados no objeto status ao chamar jobs.get.

Tabela de erros

A tabela a seguir lista os códigos de erro que o BigQuery pode retornar. As respostas da API do BigQuery incluem um código do erro HTTP e um objeto de erros no corpo da resposta. A coluna "Código do erro" abaixo mapeia para a propriedade reason no objeto de erro. Essa tabela não inclui todos os erros HTTP possíveis ou outros erros de rede. Portanto, não presuma que um objeto errors está 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 lista 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 verificar o status do job, o objeto de erro não será retornado por padrão. Para visualizar o objeto 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>

Código do 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 a ele.
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. 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.

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.
blocked 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. Isso raramente ocorre. Entre em contato com o suporte para mais informações.
duplicate 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. Repita a operação e, se o erro persistir, entre em contato com o suporte ou registre um bug usando o rastreador de problemas do BigQuery.
invalid 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 de invalidQuery.
invalidQuery 400 Este erro é retornado quando você tenta executar uma consulta inválida. Verifique se não há erros de sintaxe na 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.
notFound 404 Este erro é retornado quando você menciona um recurso (conjunto de dados, tabela ou job) que não existe. Isso também pode ocorrer ao usar decoradores de snapshot para se referir às tabelas excluídas que receberam streaming recentemente. Corrija os nomes dos recursos 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. Caso tenha recebido esse erro usando a sandbox do BigQuery, será possível fazer upgrade.

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 a consulta usa um número excessivo de recursos.
  • Tente dividir a consulta em tamanhos menores.
  • Tente remover uma cláusula ORDER BY.
  • Se a consulta usa JOIN, verifique se a tabela maior está à esquerda da cláusula.
  • Se a consulta usa FLATTEN, determine se ele é necessário no caso de uso específico. Para mais informações, consulte dados aninhados e repetidos.
  • Se a consulta usa EXACT_COUNT_DISTINCT, utilize COUNT(DISTINCT).
  • Se a consulta usa COUNT(DISTINCT <value>, <n>) com um grande valor <n>, use GROUP BY em vez disso. Para mais informações, consulte COUNT(DISTINCT).
  • Se a consulta usa UNIQUE, utilize GROUP BY em vez disso, ou use a função de janela dentro de uma subseleção.
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.
stopped 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.

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. Exemplo:

{"error":"invalid_client"}

Voltar ao início

Solução de problemas em inserções de streaming

As seguintes seções explicam como resolver erros que ocorrem ao fazer streaming de dados no BigQuery.

Códigos de resposta HTTP de falha

Se você receber um código de resposta HTTP de falha, como um erro de rede, não será possível saber se a inserção de streaming foi bem-sucedida. Se você simplesmente tentar reenviar a solicitação, poderá acabar com linhas duplicadas na tabela. Para ajudar a proteger a tabela contra duplicação, defina a property insertId ao enviar a solicitação. O BigQuery usa a property insertId para remoção da duplicação.

Se você receber um erro de permissão, de nome de tabela inválido ou de cota excedida, nenhuma linha será inserida, e a solicitação inteira falhará.

Códigos de resposta HTTP de sucesso

Mesmo que você receba um código de resposta HTTP de sucesso, será necessário verificar a property insertErrors da resposta para determinar se as inserções de linha foram bem-sucedidas, porque é possível que o BigQuery tenha conseguido inserir as linhas apenas parcialmente.

Se a property insertErrors for uma lista vazia, todas as linhas foram inseridas com êxito. Caso contrário, exceto nos casos em que houve uma incompatibilidade de esquema em qualquer uma das linhas, as linhas indicadas na property insertErrors não foram inseridas e todas as outras linhas foram inseridas com sucesso. A property errors contém informações detalhadas sobre o motivo de falha de cada linha malsucedida. A property index indica o índice de linha com base em 0 da solicitação à qual o erro se aplica.

Se o BigQuery encontrar uma incompatibilidade de esquema em linhas individuais na solicitação, nenhuma das linhas será inserida e uma entrada insertErrors será retornada para cada linha, mesmo para aquelas que não tiveram incompatibilidade de esquema. As linhas que não tiveram incompatibilidade de esquema terão um erro com a property reason definida como stopped, mas podem ser reenviadas como estão. As linhas que falharam exibem informações detalhadas sobre a incompatibilidade de esquema.

Erros de metadados para inserções de streaming

Como a API de streaming do BigQuery foi projetada para altas taxas de inserção, as modificações na exibição de metadados da tabela subjacente têm consistência eventual durante a interação com o sistema de streaming. Na maioria das vezes, as alterações de metadados são propagadas em minutos. No entanto, durante esse período, as respostas da API podem refletir o estado inconsistente da tabela.

Alguns cenários incluem:

  • Mudanças no esquema. A modificação do esquema de uma tabela que recebeu inserções de streaming recentemente pode causar respostas com erros de incompatibilidade de esquema, porque o sistema de streaming pode não captar imediatamente a alteração de esquema.
  • Criação/exclusão de tabela. Fazer streaming para uma tabela que não existe retorna uma variação de uma resposta notFound. Uma tabela criada em resposta pode não ser reconhecida imediatamente pelas inserções de streaming subsequentes. Da mesma forma, excluir ou recriar uma tabela pode criar um período em que as inserções de streaming são entregues efetivamente à tabela antiga. As inserções de streaming podem não estar presentes na nova tabela.
  • Truncamento da tabela. Truncar os dados de uma tabela (por meio de um job de consulta que usa writeDisposition de WRITE_TRUNCATE) pode causar a eliminação de inserções subsequentes durante o período de consistência.

Dados ausentes/não disponíveis

As inserções de streaming residem temporariamente no buffer de streaming, que tem características de disponibilidade diferentes do armazenamento gerenciado. Certas operações no BigQuery não interagem com o buffer de streaming, como jobs de cópia de tabela e métodos de API como tabledata.list. Os dados de streaming recentes não estarão presentes na tabela de destino ou na saída.

Voltar ao início