Questa pagina descrive i codici di stato HTTP e i messaggi di errore restituiti dall'API BigQuery. Puoi utilizzare questi codici per risolvere i problemi e gli errori delle richieste e verificare il comportamento dell'API.
Per saperne di più sugli errori non relativi alle API, sugli errori di connettività della libreria client e sugli errori della console Cloud de Confiance , consulta Messaggi di errore.
Per saperne di più sugli errori delle query, consulta Risolvi gli errori delle query.
Per saperne di più sugli errori di inserimento di flussi di dati, consulta Risolvi i problemi relativi agli inserimenti di flussi di dati.
Formato della risposta di errore
BigQuery utilizza il formato di Error Reporting HTTP standard per la sua API. Le richieste andate a buon fine restituiscono codici di stato HTTP nell'intervallo 2xx. Le richieste non riuscite restituiscono codici di stato negli intervalli 4xx e 5xx. Le richieste che richiedono un reindirizzamento restituiscono codici di stato nell'intervallo 3xx. Le risposte di errore di solito includono un documento JSON nel corpo della risposta, che contiene un oggetto di errore con informazioni sull'errore.
Nelle risposte dell'API BigQuery, un oggetto di errore è in genere uno dei seguenti:
- Un oggetto
errors, che contiene un array di oggettiErrorProto. - Un oggetto
errorResults, che contiene un singolo oggettoErrorProto.
La colonna Motivo nelle tabelle dei codici di stato di questa pagina corrisponde alla proprietà reason in un oggetto ErrorProto. Se utilizzi lo strumento a riga di comando bq per controllare lo stato del job, utilizza il flag --format=prettyjson (ad esempio bq --format=prettyjson show -j <var>JOB_ID</var>) o --apilog=stdout per visualizzare l'oggetto di errore e la relativa proprietà reason.
La tabella seguente descrive gli elementi che possono essere visualizzati nel corpo della risposta di un errore. I campi devono essere utilizzati insieme per identificare il problema. Inoltre, i valori di esempio nella tabella seguente sono a scopo illustrativo e non costituiscono un elenco esaustivo di tutti i valori possibili.
| Elemento | Descrizione |
|---|---|
code |
Un valore del codice di stato HTTP, senza la descrizione testuale. I valori di esempio includono: 400 (Richiesta non valida), 403 (Accesso negato) e 404 (Non trovato). |
error |
Un container per le informazioni sull'errore. |
errors |
Un container per i dettagli dell'errore. |
errori.domain |
L'ambito dell'errore. I valori di esempio includono: global e usageLimits. |
errori.location |
L'elemento specifico all'interno di locationType che ha causato l'errore. Ad esempio, se specifichi un valore non valido per un parametro, location sarà il nome del parametro.I valori di esempio includono: Authorization e project. |
errori.locationType |
La posizione o la parte della richiesta che ha causato l'errore. Utilizzalo con location per individuare l'errore.I valori di esempio includono header e parameter. |
errori.message |
Descrizione dell'errore. I valori di esempio includono Invalid argument, Access Denied e Not Found: Dataset myproject:foo. |
errori.reason |
Un identificatore univoco della causa dell'errore. I valori di esempio includono invalid, accessDenied e notFound. |
message |
Descrizione dell'errore. Uguale a errors.message. |
Codici di stato ed errore HTTP
Questa sezione contiene un elenco non esaustivo di codici di stato ed errore HTTP dell'API BigQuery. I codici informativi 1xx e di esito positivo 2xx vengono omessi. Per saperne di più, consulta i codici di stato della risposta in RFC 7231 §6, RFC 7232 §4, RFC 7233 §4, RFC 7235 §3 e RFC 6585.
400 - Richiesta non valida
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
badRequest |
400 |
Un'istruzione DML tenta di modificare le righe che sono state trasmesse in streaming di recente con l'API |
Esegui la migrazione all'API BigQuery Storage Write (gRPC), attendi qualche minuto per lo svuotamento del buffer di flussi di dati o filtra l'istruzione per escludere le righe inserite di recente. Per saperne di più, consulta Istruzioni DML su tabelle con un buffer di flussi. |
invalid |
400 |
La richiesta contiene un input non valido diverso da una query non valida, inclusi i seguenti casi:
|
Assicurati che gli schemi forniti corrispondano alle colonne e alle modalità esistenti, appiattisci le strutture che superano i 15 livelli di nidificazione (o archiviale come |
invalidQuery |
400 |
Una query SQL non supera i controlli di convalida o esecuzione per uno dei seguenti motivi:
|
Controlla la posizione |
jobBackendError |
400 |
In |
Riprova il job con un nuovo |
jobInternalError |
400 |
In |
Riprova a eseguire il job con un nuovo |
preconditionFailed |
400 |
Una condizione preliminare della richiesta non è soddisfatta, inclusi i seguenti casi:
|
Recupera la risorsa corrente |
resourceInUse |
400 |
Una richiesta di eliminazione ha come target una risorsa ancora attiva o compilata:
L'errore restituisce: |
Svuota il set di dati prima di eliminarlo (o imposta |
resourcesExceeded |
400 |
Un job supera i limiti delle risorse di esecuzione in una delle seguenti aree:
L'errore restituisce: |
Semplifica le query, raggruppa le operazioni DML, riduci le colonne o le partizioni scansionate, evita i job simultanei nella stessa sessione o esegui il provisioning della capacità degli slot dedicati per i workload con un elevato numero di operazioni di shuffle. Per i passaggi relativi a ciascun sottotipo, consulta Risolvi i problemi relativi al superamento delle risorse e La query supera le risorse di memoria. |
storageUnusable |
400 |
Lo spazio di archiviazione interno di BigQuery che contiene i dati della tabella non è temporaneamente disponibile a causa di un problema di archiviazione lato servizio. L'errore restituisce:
|
Riprova il job utilizzando il backoff esponenziale troncato. Per ulteriori informazioni, consulta Lo spazio di archiviazione della tabella è inutilizzabile. |
streamingDataUnavailable |
400 |
I dati trasmessi di recente in un'archiviazione ottimizzata per la scrittura non sono temporaneamente disponibili per un job di lettura. L'errore restituisce: |
Riprova a eseguire il job con un nuovo |
tableUnavailable |
400 |
BigQuery non può leggere una tabella di cui non gestisce i dati, inclusi i seguenti casi:
|
Riprova il recupero dello schema o i timeout della tabella di supporto utilizzando il backoff esponenziale troncato oppure verifica i percorsi URI Cloud Storage |
userOwnedResourceError |
400 |
Una risorsa esterna di tua proprietà restituisce un errore quando vi accede BigQuery. L'errore restituisce: |
Esamina resource_type e resource_name nel messaggio di errore per identificare la risorsa esterna e risolvere l'errore sottostante segnalato in external_error. Per saperne di più, consulta Errore della risorsa esterna di proprietà dell'utente. |
vortexDataUnavailable |
400 |
I dati di cui è stato eseguito lo streaming di recente utilizzando l'API BigQuery Storage Write (gRPC) nello spazio di archiviazione ottimizzato per la scrittura non sono temporaneamente disponibili per una query. L'errore restituisce: |
Riprova il job di query con un nuovo |
billingTierLimitExceeded |
400 |
Una query on demand supera il
limite di utilizzo massimo della CPU per i dati scansionati. L'errore restituisce: |
Rifattorizza l'SQL per rimuovere prodotti cartesiani indesiderati, join inesatti, funzioni finestra non partizionate o UDF JavaScript pesanti oppure passa ai prezzi basati sulla capacità (slot). Per saperne di più, consulta La query supera le risorse della CPU ed Evita i pattern anti-SQL. |
bytesBilledLimitExceeded |
400 |
La stima dei byte del limite superiore prima dell'esecuzione di una query supera |
Visualizza l'anteprima dei byte stimati con un dry run, seleziona solo le colonne necessarie e filtra in base alle colonne partizionate per ridurre il trattamento dei dati oppure aumenta |
jobRateLimitExceeded |
400 |
In
|
Riduci gli invii simultanei (o utilizza la priorità batch o la scalabilità automatica degli slot per le query continue) e riprova il job con un nuovo |
timeout |
400 |
Un'operazione supera il limite di tempo di esecuzione, inclusi i seguenti casi:
|
Filtra in base alle colonne partizionate o raggruppate in cluster e suddividi le query complesse o con più istruzioni in fasi più piccole oppure specifica uno schema esplicito e URI di origine più ristretti durante la creazione di tabelle esterne. Per ulteriori informazioni, consulta La query supera il limite di tempo di esecuzione e Risolvi gli errori relativi a quote e limiti. |
invalidUser |
400 |
Una query pianificata è stata configurata con credenziali utente non valide. |
Aggiorna le credenziali utente per la query pianificata. Per saperne di più, consulta Pianificazione delle query. |
required |
400 |
Manca un input obbligatorio prima dell'esecuzione:
L'errore restituisce: |
Verifica il corpo della richiesta e parametri di ricerca obbligatori nel riferimento API BigQuery o nella documentazione della libreria client e controlla l'oggetto di configurazione prima di chiamare l'API. Per saperne di più, consulta Parametro obbligatorio mancante. |
401 - Unauthorized
Di seguito è riportato un esempio di risposta di errore che ricevi se la tua richiesta non contiene credenziali di autenticazione valide.
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 | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
unauthenticated |
401 |
L'autenticazione della richiesta non va a buon fine per uno dei seguenti motivi:
|
Aggiorna le Credenziali predefinite dell'applicazione o OAuth, concedi |
403 — Forbidden
Questo è un esempio di risposta di errore che ricevi se non hai l'autorizzazione per accedere alla risorsa richiesta.
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 | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
responseTooLarge |
403 |
Una risposta di lettura di una query o di una tabella supera i limiti di dimensioni in uno dei seguenti modi:
L'errore restituisce: |
Specifica una tabella di destinazione (e imposta |
apiLimitExceeded |
403 |
Una richiesta supera uno dei seguenti limiti relativi all'API o ai metadati:
L'errore restituisce: |
Riprova le richieste non riuscite con backoff esponenziale troncato, carichi e letture in batch, semplifica le policy di sicurezza IAM granulari per tabella o a livello di riga e attendi la finestra temporale prima di aggiungere repliche del set di dati. Per maggiori informazioni, consulta Errori relativi alla frequenza delle API e al limite di valutazione dei metadati ed Errori relativi al limite di creazione delle repliche dei set di dati tra regioni. |
quotaExceeded |
403 |
Il tuo progetto supera una delle seguenti quote di utilizzo:
L'errore restituisce: |
Esamina l'errore |
rateLimitExceeded |
403 |
Una richiesta viene rifiutata per uno dei seguenti limiti di frequenza o contemporaneità:
|
Riduci il tasso di richieste e riprova utilizzando il backoff esponenziale troncato oppure esegui query non urgenti con priorità batch e regola la contemporaneità delle prenotazioni o la scalabilità automatica degli slot. Per saperne di più, consulta Risolvi gli errori relativi a quote e limiti e Query admission denied. |
accessDenied |
403 |
L'accesso a una risorsa BigQuery viene negato per uno dei seguenti motivi:
L'errore restituisce: |
Esamina
Cloud Audit Logs
( |
policyViolation |
403 |
Un perimetro di sicurezza o una policy dell'organizzazione blocca la richiesta:
|
Filtra Esplora log in base a |
billingNotEnabled |
403 |
Il progetto non dispone di un account di fatturazione attivo per l'operazione richiesta:
L'errore restituisce: |
Abilita la fatturazione per il progetto nella console Cloud de Confiance per eseguire l'upgrade dalla sandbox di BigQuery, quindi aggiorna le date di scadenza predefinite per tabelle, viste e partizioni. Per saperne di più, consulta La fatturazione non è abilitata per il progetto. |
blocked |
403 |
BigQuery ha aggiunto temporaneamente l'operazione tentata a una lista bloccata per evitare un'interruzione del servizio. L'errore restituisce: |
Contatta l'assistenza clienti Google Cloud con il timestamp esatto, l'ID progetto e l'ID job BigQuery per esaminare la regola di mitigazione amministrativa. Per saperne di più, consulta La richiesta è stata bloccata per proteggere il funzionamento del sistema. |
termsOfServiceNotAccepted |
403 |
Il progetto non ha accettato i Termini di servizio di BigQuery. L'errore restituisce: |
Accedi alla consoleCloud de Confiance , seleziona il tuo paese e la casella di controllo dei Termini di servizio nella pagina di benvenuto, se richiesto, quindi fai clic su Accetta e continua. Per saperne di più, consulta Termini di servizio di BigQuery non accettati. |
404 - Non trovato
Di seguito è riportato un esempio di risposta di errore che ricevi se provi a recuperare un set di dati o una risorsa che non esiste.
404 Not Found
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "Not Found: Dataset myproject:foo"
}
],
"code": 404,
"message": "Not Found: Dataset myproject:foo"
}
}
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
notFound |
404 |
Impossibile trovare una risorsa richiesta per uno dei seguenti motivi:
L'errore restituisce: |
Verifica l'identificatore e la località esatti del progetto, del set di dati e della tabella, sensibili alle maiuscole, ripristina le tabelle eliminate nella finestra di viaggio nel tempo, esegui nuovamente le query le cui tabelle dei risultati memorizzate nella cache sono scadute o verifica l'esistenza di file esterni di Cloud Storage o Google Drive. Per ulteriori informazioni, vedi Tabella non trovata, Località non trovata e Job non trovato. |
409 - Conflict
Di seguito è riportato un esempio di risposta di errore che ricevi se provi a creare una risorsa già esistente.
409 Conflict
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "Already Exists: Dataset myproject:mydataset"
}
],
"code": 409,
"message": "Already Exists: Dataset myproject:mydataset"
}
}
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
abortd |
409 |
Un'operazione si interrompe a causa di una modifica o di un conflitto simultaneo (restituito con il motivo |
Riprova l'operazione al termine dell'operazione in conflitto utilizzando il backoff esponenziale troncato oppure esegui il rollback delle transazioni con più istruzioni interrotte prima di riprovare. Per saperne di più, consulta L'operazione è stata interrotta. |
duplicate |
409 |
Una richiesta è in conflitto con una risorsa esistente in uno dei seguenti modi:
L'errore restituisce: |
Utilizza un nome di risorsa diverso, utilizza |
499 - Client closed request
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
stopped |
499 |
Un job si interrompe prima del completamento per uno dei seguenti motivi (il polling di
L'errore restituisce: |
Aumenta le opzioni di timeout della coda del progetto o di |
500 - Errore interno del server
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
internalError |
500 |
Si è verificato un errore interno in BigQuery. L'errore restituisce:
|
Attendi in base ai requisiti di backoff indicati nell'accordo sul livello del servizio BigQuery e riprova utilizzando il backoff esponenziale troncato oppure utilizza Prenotazioni per ridurre la frequenza degli errori temporanei. Per saperne di più, consulta Risolvi gli errori internalError. |
501 - Non implementata
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
notImplemented |
501 |
Una richiesta tenta di utilizzare una funzionalità o un'operazione non implementata per la risorsa di destinazione, ad esempio:
L'errore restituisce: |
Materializza le origini di copia delle tabelle non supportate utilizzando |
503 - Servizio non disponibile
| Motivo | Codice di stato HTTP | Descrizione | Risoluzione dei problemi |
|---|---|---|---|
backendError |
503 |
Il servizio non è al momento disponibile per uno dei seguenti motivi:
L'errore restituisce: |
Riprova a inviare le richieste utilizzando il backoff esponenziale troncato e riprova a eseguire i job non riusciti con un nuovo |