Nesta página, descrevemos os códigos de status HTTP e as mensagens de erro retornados pela API BigQuery. Use esses códigos para resolver problemas e falhas de solicitação, além de verificar o comportamento da API.
Para mais informações sobre erros que não são da API, erros de conectividade da biblioteca de cliente e erros do console do Google Cloud , consulte Mensagens de erro.
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.
Formato da resposta de erro
O BigQuery usa o formato padrão de relatório de erros HTTP para a
API. As solicitações bem-sucedidas retornam códigos de status HTTP no intervalo 2xx. As solicitações com falha retornam códigos de status nos intervalos 4xx e 5xx. As solicitações que
exigem um redirecionamento retornam códigos de status no intervalo 3xx. As respostas de erro
geralmente incluem um documento JSON no corpo da resposta, que contém um objeto
de erro com informações sobre o erro.
Nas respostas da API BigQuery, um objeto de erro geralmente é um dos seguintes:
- Um objeto
errors, que contém uma matriz de objetosErrorProto. - Um objeto
errorResults, que contém um único objetoErrorProto.
A coluna Motivo nas tabelas de código de status nesta página é mapeada para a propriedade reason em um objeto ErrorProto. Se você usar a
ferramenta de linha de comando bq para verificar o status do job, use
a flag --format=prettyjson (por exemplo,
bq --format=prettyjson show -j <var>JOB_ID</var>) ou --apilog=stdout para visualizar
o objeto de erro e a propriedade reason dele.
A tabela a seguir descreve os elementos que podem aparecer no corpo da resposta de um erro. Os campos devem ser usados juntos para ajudar a determinar o problema. Além disso, os valores de exemplo na tabela a seguir são para fins de ilustração e não são uma lista completa de todos os valores possíveis.
| Elemento | Descrição |
|---|---|
code |
Um valor de código de status HTTP, sem a descrição textual. Exemplos de valores: 400 (Bad Request), 403 (Forbidden) e 404 (Not Found). |
error |
Um contêiner para as informações de erro. |
errors |
Um contêiner para os detalhes do erro. |
erros.domain |
O escopo do erro. Exemplos de valores: global e usageLimits. |
erros.location |
O item específico dentro de locationType que causou o erro. Por exemplo, se você especificar um valor inválido para um parâmetro, o location será o nome do parâmetro.Exemplos de valores: Authorization e project. |
erros.locationType |
O local ou a parte da solicitação que causou o erro. Use com location para identificar o erro.Exemplos de valores incluem header e parameter. |
erros.message |
Descrição do erro. Exemplos de valores incluem Invalid argument, Access Denied e Not Found: Dataset myproject:foo. |
erros.reason |
Um identificador exclusivo para a causa do erro. Exemplos de valores incluem invalid, accessDenied e notFound. |
message |
Descrição do erro. Igual a errors.message. |
Códigos de status e código do erro HTTP
Esta seção contém alguns exemplos de códigos de status e código do erro HTTP da API BigQuery. Os códigos informativos 1xx e de sucesso 2xx são omitidos. Para mais informações, consulte os códigos de status de resposta
em RFC 7231 §6, RFC 7232 §4,
RFC 7233 §4, RFC 7235 §3 e RFC 6585.
400 — Solicitação inválida
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
badRequest |
400 |
Uma instrução DML tenta modificar linhas que foram transmitidas recentemente com a
API |
Migre para a API BigQuery Storage Write (gRPC), aguarde alguns minutos para que o buffer de streaming seja limpo ou filtre a instrução para excluir as linhas transmitidas recentemente. Para mais informações, consulte Instruções DML em tabelas com um buffer de streaming. |
invalid |
400 |
A solicitação contém uma entrada inválida que não é uma consulta inválida, incluindo os seguintes casos:
|
Verifique se os esquemas fornecidos correspondem às colunas e aos modos atuais, simplifique as estruturas
com mais de 15 níveis de aninhamento (ou armazene-as como |
invalidQuery |
400 |
Uma consulta SQL falha nas verificações de validação ou execução por um dos seguintes motivos:
|
Verifique o local |
jobBackendError |
400 |
No |
Tente novamente o job com um novo |
jobInternalError |
400 |
Em |
Tente novamente com um novo |
preconditionFailed |
400 |
Uma condição prévia da solicitação não é atendida, incluindo os seguintes casos:
|
Busque o recurso atual |
resourceInUse |
400 |
Uma solicitação de exclusão tem como alvo um recurso que ainda está ativo ou preenchido:
O erro retorna: |
Esvazie o conjunto de dados antes de excluí-lo (ou defina
|
resourcesExceeded |
400 |
Um job excede os limites de recursos de execução em uma das seguintes áreas:
O erro retorna: |
Simplifique as consultas, agrupe as operações de DML, reduza as colunas ou partições verificadas, evite jobs simultâneos na mesma sessão ou provisione capacidade de slot dedicada para cargas de trabalho com muita mistura. Para ver as etapas por subtipo, consulte Resolver problemas de recursos excedidos e A consulta excede os recursos de memória. |
storageUnusable |
400 |
O armazenamento interno do BigQuery que contém os dados da tabela está
temporariamente indisponível devido a um problema de armazenamento no serviço. O erro retorna:
|
Tente novamente usando a espera exponencial truncada. Para mais informações, consulte O armazenamento de tabelas está inutilizável. |
streamingDataUnavailable |
400 |
Os dados transmitidos recentemente no armazenamento otimizado para gravação ficam temporariamente indisponíveis
para um job de leitura. O erro retorna: |
Tente novamente o job com um novo |
tableUnavailable |
400 |
O BigQuery não pode ler uma tabela com dados que ele não gerencia, incluindo os seguintes casos:
|
Tente buscar o esquema novamente ou use a espera exponencial truncada para resolver os tempos limite da tabela de apoio. Outra opção é verificar os caminhos de URI do Cloud Storage de |
userOwnedResourceError |
400 |
Um recurso externo de sua propriedade retorna um erro quando acessado pelo BigQuery. O erro retorna: |
Inspecione resource_type e resource_name na mensagem de erro para identificar o recurso externo e resolver o erro subjacente informado em external_error. Para mais informações, consulte Erro de recurso externo de propriedade do usuário. |
vortexDataUnavailable |
400 |
Os dados transmitidos recentemente usando a API BigQuery Storage Write (gRPC) para o armazenamento otimizado para gravação ficam temporariamente indisponíveis para uma consulta. O erro retorna: |
Tente novamente o job de consulta com um novo |
billingTierLimitExceeded |
400 |
Uma consulta on demand excede o
limite máximo de uso da CPU por dados
verificados. O erro retorna: |
Refatore o SQL para remover produtos cartesianos não intencionais, mesclagens inexatas, funções de janela não particionadas ou UDFs pesadas do JavaScript ou mude para preços baseados em capacidade (slots). Para mais informações, consulte A consulta excede os recursos de CPU e Evite padrões anti-SQL. |
bytesBilledLimitExceeded |
400 |
A estimativa de bytes de limite superior pré-execução para uma consulta excede
|
Visualize os bytes estimados com uma
simulação, selecione apenas as colunas
necessárias e filtre as colunas particionadas para
reduzir
o tratamento de dados ou aumente |
jobRateLimitExceeded |
400 |
No
|
Reduza os envios simultâneos (ou use a prioridade em lote ou o escalonamento automático de slots para
consultas contínuas) e tente novamente o job com um novo |
timeout |
400 |
Uma operação excede o limite de tempo de execução, incluindo os seguintes casos:
|
Filtre em colunas particionadas ou em cluster e divida consultas complexas ou de várias instruções em etapas menores ou especifique um esquema explícito e URIs de origem mais restritos ao criar tabelas externas. Para mais informações, consulte A consulta excede o limite de tempo de execução e Resolver erros de cota e limite. |
invalidUser |
400 |
Uma consulta programada foi configurada com credenciais de usuário inválidas. |
Atualize as credenciais do usuário para a consulta programada. Para mais informações, consulte Como programar consultas. |
required |
400 |
Uma entrada obrigatória está ausente antes da execução:
O erro retorna: |
Verifique o corpo da solicitação e os parâmetros de consulta necessários na referência da API BigQuery ou na documentação da biblioteca de cliente e inspecione o objeto de configuração antes de chamar a API. Para mais informações, consulte Parâmetro obrigatório ausente. |
401 — Não autorizado
Veja a seguir um exemplo de resposta de erro que você recebe se a solicitação não tiver credenciais de autenticação válidas.
401 Unauthorized
{
"error": {
"errors": [
{
"domain": "global",
"reason": "unauthenticated",
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential."
}
],
"code": 401,
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
"status": "UNAUTHENTICATED"
}
}
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
unauthenticated |
401 |
A autenticação da solicitação falha por um dos seguintes motivos:
|
Atualize o OAuth ou o Application Default Credentials, conceda
|
403 — Forbidden
Este é um exemplo de resposta de erro que você recebe se não tiver permissão para acessar o recurso solicitado.
403 Forbidden
{
"error": {
"errors": [
{
"domain": "global",
"reason": "accessDenied",
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
],
"code": 403,
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
}
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
responseTooLarge |
403 |
Uma resposta de leitura de consulta ou tabela excede os limites de tamanho de uma das seguintes maneiras:
O erro retorna: |
Especifique uma tabela de destino (e defina
|
apiLimitExceeded |
403 |
Uma solicitação excede um dos seguintes limites de API ou de metadados:
O erro retorna: |
Tente novamente as solicitações com falha com espera exponencial truncada, leituras e carregamentos em lote, simplifique as políticas de segurança granulares por tabela do IAM ou no nível da linha e aguarde a janela contínua antes de adicionar réplicas de conjunto de dados. Para mais informações, consulte Erros de limite de avaliação de metadados e taxa de API e Erros de limite de criação de réplica de conjunto de dados entre regiões. |
quotaExceeded |
403 |
Seu projeto excede uma das seguintes cotas de uso:
O erro retorna: |
Inspecione o erro |
rateLimitExceeded |
403 |
Uma solicitação é rejeitada por um dos seguintes limites de taxa ou simultaneidade:
|
Reduza a taxa de solicitação e tente novamente usando a espera exponencial truncada ou execute consultas não urgentes com prioridade de lote e ajuste a simultaneidade de reserva ou o escalonamento automático de slots. Para mais informações, consulte Resolver erros de cota e limite e Admissão de consulta negada. |
accessDenied |
403 |
O acesso a um recurso do BigQuery é negado por um dos seguintes motivos:
O erro retorna: |
Inspecione os
Registros de auditoria do Cloud
( |
policyViolation |
403 |
Um perímetro de segurança ou uma política da organização bloqueia a solicitação:
|
Filtre a Análise de registros por |
billingNotEnabled |
403 |
O projeto não tem faturamento ativo para a operação solicitada:
O erro retorna: |
Ative o faturamento do projeto no console doGoogle Cloud para fazer upgrade do sandbox do BigQuery e atualize os prazos de validade padrão das tabelas, visualizações e partições. Para mais informações, consulte O faturamento não está ativado para o projeto. |
blocked |
403 |
O BigQuery adicionou temporariamente a operação tentada a uma
lista de bloqueio para evitar uma interrupção do serviço. O erro retorna: |
Entre em contato com o Cloud Customer Care com o carimbo de data/hora exato, o ID do projeto e o código da tarefa do BigQuery para investigar a regra de mitigação administrativa. Para mais informações, consulte A solicitação foi bloqueada para proteger a operação do sistema. |
termsOfServiceNotAccepted |
403 |
O projeto não aceitou os Termos de Serviço do BigQuery. O
erro retorna: |
Faça login no console doGoogle Cloud , selecione seu país e marque a caixa de seleção dos Termos de Serviço na página de recepção, se solicitado, e clique em Concordar e continuar. Para mais informações, consulte Termos de Serviço do BigQuery não aceitos. |
404 — Não encontrado
Veja a seguir um exemplo de resposta de erro que você recebe se tentar recuperar um conjunto de dados ou recurso que não existe.
404 Not Found
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "Not Found: Dataset myproject:foo"
}
],
"code": 404,
"message": "Not Found: Dataset myproject:foo"
}
}
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
notFound |
404 |
Um recurso solicitado não foi encontrado por um dos seguintes motivos:
O erro retorna: |
Verifique o identificador e o local exatos do projeto, do conjunto de dados e da tabela, que diferenciam maiúsculas de minúsculas, restaure tabelas excluídas dentro da janela de viagem no tempo, execute novamente as consultas cujas tabelas de resultados armazenadas em cache expiraram ou confirme se os arquivos externos do Cloud Storage ou do Google Drive existem. Para mais informações, consulte Tabela não encontrada, Local não encontrado e Job não encontrado. |
409 — Conflito
Veja a seguir um exemplo de resposta de erro que você recebe se tentar criar um recurso que já existe.
409 Conflict
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "Already Exists: Dataset myproject:mydataset"
}
],
"code": 409,
"message": "Already Exists: Dataset myproject:mydataset"
}
}
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
abortd |
409 |
Uma operação é interrompida devido a uma modificação ou conflito simultâneo (retornado
com o motivo |
Tente realizar a operação novamente depois que a operação conflitante for concluída usando a espera exponencial truncada ou reverter as transações de várias instruções interrompidas antes de tentar novamente. Para mais informações, consulte A operação foi cancelada. |
duplicate |
409 |
Uma solicitação entra em conflito com um recurso atual de uma das seguintes maneiras:
O erro retorna: |
Use um nome de recurso diferente, use |
499 — Solicitação fechada pelo cliente
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
stopped |
499 |
Um job é interrompido antes da conclusão por um dos seguintes motivos (a sondagem
O erro retorna: |
Aumente as opções de tempo limite da fila de projetos ou de |
500 — Erro interno do servidor
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
internalError |
500 |
Ocorreu um erro interno no BigQuery. O erro retorna:
|
Aguarde de acordo com os requisitos de espera no Contrato de nível de serviço do BigQuery e tente novamente usando a espera exponencial truncada ou use Reservas para reduzir a frequência de erros temporários. Para mais informações, consulte Resolver erros internalError. |
501 — Não implementado
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
notImplemented |
501 |
Uma solicitação tenta usar um recurso ou uma operação não implementada para o recurso de destino, como:
O erro retorna: |
Materialize origens de cópia de tabela não compatíveis usando |
503 — Serviço indisponível
| Motivo | Código de status HTTP | Descrição | Solução de problemas |
|---|---|---|---|
backendError |
503 |
O serviço está temporariamente indisponível por um dos seguintes motivos:
O erro retorna: |
Tente novamente as solicitações usando a
espera exponencial
truncada e tente novamente os jobs com falha com um novo |