Cette page décrit les codes d'état HTTP et les messages d'erreur renvoyés par l'API BigQuery. Vous pouvez utiliser ces codes pour résoudre les problèmes et les échecs de requêtes, et vérifier le comportement de l'API.
Pour en savoir plus sur les erreurs non liées à l'API, les erreurs de connectivité de la bibliothèque cliente et les erreurs de la console Cloud de Confiance , consultez Messages d'erreur.
Pour en savoir plus sur les erreurs de requête, consultez la page Résoudre les erreurs de requête.
Pour en savoir plus sur les erreurs d'insertion en flux continu, consultez la page Résoudre les problèmes liés à l'insertion en flux continu.
Format de réponse d'erreur
BigQuery utilise le format de rapport d'erreur HTTP standard pour son API. Les requêtes réussies renvoient des codes d'état HTTP de la plage 2xx. Les requêtes ayant échoué renvoient des codes d'état compris entre 4xx et 5xx. Les requêtes qui nécessitent une redirection renvoient des codes d'état de la plage 3xx. Les réponses d'erreur incluent généralement un document JSON dans le corps de la réponse, qui contient un objet d'erreur avec des informations sur l'erreur.
Dans les réponses de l'API BigQuery, un objet d'erreur est généralement l'un des éléments suivants :
- Un objet
errors, qui contient un tableau d'objetsErrorProto. - Un objet
errorResults, qui contient un seul objetErrorProto.
La colonne Motif des tableaux de codes d'état de cette page correspond à la propriété reason d'un objet ErrorProto. Si vous utilisez l'outil de ligne de commande bq pour vérifier l'état d'un job, utilisez l'option --format=prettyjson (par exemple, bq --format=prettyjson show -j <var>JOB_ID</var>) ou --apilog=stdout pour afficher l'objet d'erreur et sa propriété reason.
Le tableau suivant décrit les éléments pouvant apparaître dans le corps de réponse d'une erreur. Les champs doivent être utilisés ensemble pour aider à déterminer le problème. De plus, les exemples de valeurs du tableau suivant sont fournis à titre d'illustration et ne constituent pas une liste exhaustive de toutes les valeurs possibles.
| Élément | Description |
|---|---|
code |
Valeur de code d'état HTTP, sans la description textuelle. Exemples de valeurs : 400 (Requête incorrecte), 403 (Interdit) et 404 (Introuvable). |
error |
Conteneur pour les informations d'erreur. |
errors |
Conteneur pour les détails de l'erreur. |
errors.domain |
Champ d'application de l'erreur. Exemples de valeurs : global et usageLimits. |
errors.location |
Élément spécifique de l'locationType à l'origine de l'erreur. Par exemple, si vous spécifiez une valeur non valide pour un paramètre, location sera le nom du paramètre.Exemples de valeurs : Authorization et project. |
errors.locationType |
Emplacement ou partie de la requête à l'origine de l'erreur. Utilisez-le avec location pour identifier l'erreur.Exemples de valeurs : header et parameter. |
errors.message |
Description de l'erreur. Exemples de valeurs : Invalid argument, Access Denied et Not Found: Dataset myproject:foo. |
errors.reason |
Identifiant unique de la cause de l'erreur. Exemples de valeurs : invalid, accessDenied et notFound. |
message |
Description de l'erreur. Identique à errors.message. |
Codes d'état et d'erreur HTTP
Cette section contient une liste non exhaustive des codes d'état et d'erreur HTTP de l'API BigQuery. Les codes d'information 1xx et de réussite 2xx sont omis. Pour en savoir plus, consultez les codes d'état de réponse dans les documents RFC 7231 §6, RFC 7232 §4, RFC 7233 §4, RFC 7235 §3 et RFC 6585.
400 — Requête incorrecte
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
badRequest |
400 |
Une instruction LMD tente de modifier des lignes qui ont été récemment diffusées avec l'ancienne API |
Migrez vers l'API BigQuery Storage Write (gRPC), attendez quelques minutes que le tampon de flux soit vidé ou filtrez votre instruction pour exclure les lignes récemment diffusées. Pour en savoir plus, consultez Instructions LMD sur les tables avec un tampon de flux de données. |
invalid |
400 |
La requête contient une entrée non valide autre qu'une requête non valide, y compris dans les cas suivants :
|
Assurez-vous que les schémas fournis correspondent aux colonnes et aux modes existants, aplatissez les structures dépassant 15 niveaux d'imbrication (ou stockez-les au format |
invalidQuery |
400 |
La validation ou l'exécution d'une requête SQL échoue pour l'une des raisons suivantes :
|
Vérifiez l'emplacement |
jobBackendError |
400 |
Dans |
Relancez le job avec un nouveau |
jobInternalError |
400 |
Dans |
Réessayez d'exécuter la tâche avec un nouveau |
preconditionFailed |
400 |
Une condition préalable de la requête n'est pas remplie, y compris dans les cas suivants :
|
Récupérez la ressource actuelle |
resourceInUse |
400 |
Une requête de suppression cible une ressource qui est toujours active ou renseignée :
L'erreur renvoie : |
Videz l'ensemble de données avant de le supprimer (ou définissez |
resourcesExceeded |
400 |
Un job dépasse les limites de ressources d'exécution dans l'un des domaines suivants :
L'erreur renvoie : |
Simplifiez les requêtes, effectuez des opérations LMD par lot, réduisez le nombre de colonnes ou de partitions analysées, évitez les jobs simultanés dans la même session ou provisionnez une capacité d'emplacements dédiée pour les charges de travail nécessitant de nombreux brassages. Pour connaître les étapes par sous-type, consultez Résoudre les problèmes de dépassement de ressources et La requête dépasse les ressources de mémoire. |
storageUnusable |
400 |
L'espace de stockage BigQuery interne contenant les données de la table est temporairement indisponible en raison d'un problème de stockage côté service. L'erreur renvoie :
|
Réessayez d'exécuter la tâche en utilisant un intervalle exponentiel tronqué entre les tentatives. Pour en savoir plus, consultez Le stockage de la table est inutilisable. |
streamingDataUnavailable |
400 |
Les données récemment soumises au traitement par flux dans le stockage optimisé en écriture sont temporairement indisponibles pour un job de lecture. L'erreur renvoie : |
Relancez le job avec un nouveau |
tableUnavailable |
400 |
BigQuery ne peut pas lire une table dont il ne gère pas les données, y compris dans les cas suivants :
|
Réessayez de récupérer le schéma ou les délais d'expiration de la table de sauvegarde à l'aide d'un intervalle exponentiel entre les tentatives tronqué, ou vérifiez les chemins d'URI Cloud Storage |
userOwnedResourceError |
400 |
Une ressource externe dont vous êtes propriétaire renvoie une erreur lorsqu'elle est consultée par BigQuery. L'erreur renvoie : |
Inspectez resource_type et resource_name dans le message d'erreur pour identifier la ressource externe, puis résolvez l'erreur sous-jacente signalée dans external_error. Pour en savoir plus, consultez Erreur de ressource externe appartenant à l'utilisateur. |
vortexDataUnavailable |
400 |
Les données récemment diffusées à l'aide de l'API BigQuery Storage Write (gRPC) dans un espace de stockage optimisé en écriture sont temporairement indisponibles pour une requête. L'erreur renvoie : |
Relancez le job de requête avec un nouveau |
billingTierLimitExceeded |
400 |
Une requête à la demande dépasse la limite d'utilisation maximale du processeur par données analysées. L'erreur renvoie : |
Refactorisez votre code SQL pour supprimer les produits cartésiens involontaires, les jointures inexactes, les fonctions de fenêtrage non partitionnées ou les fonctions JavaScript définies par l'utilisateur lourdes, ou passez à la tarification basée sur la capacité (emplacements). Pour en savoir plus, consultez La requête dépasse les ressources du processeur et Éviter les antimodèles SQL. |
bytesBilledLimitExceeded |
400 |
L'estimation de la limite supérieure d'octets avant l'exécution d'une requête dépasse |
Prévisualisez les octets estimés avec un dry run, sélectionnez uniquement les colonnes nécessaires et filtrez les colonnes partitionnées pour réduire les données traitées, ou augmentez |
jobRateLimitExceeded |
400 |
Dans
|
Réduisez le nombre d'envois simultanés (ou utilisez la priorité par lot ou l'autoscaling des emplacements pour les requêtes continues), puis relancez le job avec un nouveau |
timeout |
400 |
Une opération dépasse son délai d'exécution, y compris dans les cas suivants :
|
Filtrez sur des colonnes partitionnées ou en cluster, et divisez les requêtes complexes ou à plusieurs instructions en étapes plus petites, ou spécifiez un schéma explicite et des URI sources plus étroits lors de la création de tables externes. Pour en savoir plus, consultez La requête dépasse le délai d'exécution et Résoudre les erreurs de quota et de limite. |
invalidUser |
400 |
Une requête programmée a été configurée avec des identifiants utilisateur non valides. |
Actualisez les identifiants utilisateur de la requête programmée. Pour en savoir plus, consultez Planifier des requêtes. |
required |
400 |
Une entrée obligatoire est manquante avant l'exécution :
L'erreur renvoie : |
Vérifiez les paramètres de requête et le corps de la requête requis dans la documentation de référence de l'API BigQuery ou dans la documentation de la bibliothèque cliente, puis inspectez l'objet de configuration avant d'appeler l'API. Pour en savoir plus, consultez Paramètre obligatoire manquant. |
401 — Non autorisé
Voici un exemple de réponse d'erreur que vous recevez si votre requête ne contient pas d'identifiants d'authentification valides.
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"
}
}
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
unauthenticated |
401 |
L'authentification de la requête échoue pour l'une des raisons suivantes :
|
Actualisez vos Identifiants par défaut de l'application ou OAuth, accordez |
403 — Forbidden
Voici un exemple de réponse d'erreur que vous recevez si vous n'êtes pas autorisé à accéder à la ressource demandée.
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."
}
}
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
responseTooLarge |
403 |
Une réponse de lecture de requête ou de table dépasse les limites de taille de l'une des manières suivantes :
L'erreur renvoie : |
Spécifiez une table de destination (et définissez |
apiLimitExceeded |
403 |
Une requête dépasse l'une des limites d'API ou de métadonnées suivantes :
L'erreur renvoie : |
Réessayez les requêtes ayant échoué avec une intervalle exponentiel entre les tentatives tronqué, des chargements et des lectures par lot, simplifiez les règles de sécurité IAM précises par table ou au niveau des lignes, et attendez la fenêtre glissante avant d'ajouter des instances répliquées d'ensemble de données. Pour en savoir plus, consultez les sections Erreurs de limite d'évaluation des métadonnées et du taux d'API et Erreurs de limite de création d'instances répliquées d'ensembles de données interrégionaux. |
quotaExceeded |
403 |
Votre projet dépasse l'un des quotas d'utilisation suivants :
L'erreur renvoie : |
Inspectez l'erreur |
rateLimitExceeded |
403 |
Une requête est refusée pour l'une des limites de débit ou de simultanéité suivantes :
|
Réduisez le taux de requêtes et réessayez en utilisant un intervalle exponentiel tronqué entre les tentatives, ou exécutez les requêtes non urgentes avec une priorité par lot et ajustez la simultanéité des réservations ou l'autoscaling des emplacements. Pour en savoir plus, consultez Résoudre les erreurs de quota et de limite et Refus d'admission de la requête. |
accessDenied |
403 |
L'accès à une ressource BigQuery est refusé pour l'une des raisons suivantes :
L'erreur renvoie : |
Inspectez les journaux d'audit Cloud ( |
policyViolation |
403 |
Un périmètre de sécurité ou une règle d'administration bloque la requête :
|
Filtrez l'explorateur de journaux par |
billingNotEnabled |
403 |
La facturation n'est pas activée pour le projet pour l'opération demandée :
L'erreur renvoie : |
Activez la facturation pour le projet dans la consoleCloud de Confiance pour effectuer une mise à niveau depuis le bac à sable BigQuery, puis mettez à jour les délais d'expiration par défaut pour vos tables, vues et partitions. Pour en savoir plus, consultez La facturation n'est pas activée pour le projet. |
blocked |
403 |
BigQuery a temporairement ajouté l'opération tentée à une liste de blocage pour éviter une interruption de service. L'erreur renvoie : |
Contactez Cloud Customer Care en indiquant le code temporel exact, l'ID du projet et l'ID du job BigQuery pour examiner la règle de correction administrative. Pour en savoir plus, consultez La requête a été bloquée pour protéger le fonctionnement du système. |
termsOfServiceNotAccepted |
403 |
Les conditions d'utilisation de BigQuery n'ont pas été acceptées pour le projet. L'erreur renvoie : |
Connectez-vous à la consoleCloud de Confiance , sélectionnez votre pays et cochez la case "Conditions d'utilisation" sur la page de bienvenue si vous y êtes invité, puis cliquez sur Accepter et continuer. Pour en savoir plus, consultez Conditions d'utilisation de BigQuery non acceptées. |
404 — Introuvable
Voici un exemple de réponse d'erreur que vous recevez si vous essayez de récupérer un ensemble de données ou une ressource qui n'existe pas.
404 Not Found
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "Not Found: Dataset myproject:foo"
}
],
"code": 404,
"message": "Not Found: Dataset myproject:foo"
}
}
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
notFound |
404 |
Une ressource demandée est introuvable pour l'une des raisons suivantes :
L'erreur renvoie : |
Vérifiez l'identifiant et l'emplacement exacts du projet, de l'ensemble de données et de la table (sensibles à la casse), restaurez les tables supprimées dans la fenêtre temporelle, réexécutez les requêtes dont les tables de résultats mises en cache ont expiré, ou confirmez l'existence des fichiers Cloud Storage ou Google Drive externes. Pour en savoir plus, consultez Table non trouvée, Emplacement non trouvé et Job non trouvé. |
409 — Conflit
Voici un exemple de réponse d'erreur que vous recevez si vous essayez de créer une ressource qui existe déjà.
409 Conflict
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "Already Exists: Dataset myproject:mydataset"
}
],
"code": 409,
"message": "Already Exists: Dataset myproject:mydataset"
}
}
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
abortd |
409 |
Une opération s'arrête en raison d'une modification simultanée ou d'un conflit (renvoyé avec le motif |
Réessayez l'opération une fois l'opération en conflit terminée à l'aide d'un intervalle exponentiel tronqué entre les tentatives, ou effectuez un rollback des transactions à plusieurs instructions arrêtées avant de réessayer. Pour en savoir plus, consultez L'opération a été abandonnée. |
duplicate |
409 |
Une requête entre en conflit avec une ressource existante de l'une des manières suivantes :
L'erreur renvoie : |
Utilisez un autre nom de ressource, utilisez |
499 — Requête fermée par le client
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
stopped |
499 |
Un job s'arrête avant la fin pour l'une des raisons suivantes (l'interrogation de
L'erreur renvoie : |
Augmentez les options de délai avant expiration de la file d'attente du projet ou de |
500 : erreur interne du serveur
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
internalError |
500 |
Une erreur interne s'est produite dans BigQuery. L'erreur renvoie :
|
Attendez conformément aux exigences de l'accord de niveau de service BigQuery, puis réessayez en utilisant l'intervalle exponentiel tronqué entre les tentatives ou utilisez les réservations pour réduire la fréquence des erreurs temporaires. Pour en savoir plus, consultez Résoudre les erreurs internalError. |
501 — Non implémenté
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
notImplemented |
501 |
Une requête tente d'utiliser une fonctionnalité ou une opération non implémentée pour la ressource cible, par exemple :
L'erreur renvoie : |
Matérialisez les sources de copie de table non compatibles à l'aide de |
503 — Service indisponible
| Motif | HTTP Status Code | Description | Dépannage |
|---|---|---|---|
backendError |
503 |
Le service est momentanément indisponible pour l'une des raisons suivantes :
L'erreur renvoie : |
Réessayez les requêtes à l'aide d'un intervalle exponentiel tronqué entre les tentatives, et réessayez les jobs ayant échoué avec un nouveau |