Corriger les erreurs

L'API Google Drive renvoie deux niveaux d'informations d'erreur:

  • Codes d'erreur HTTP et messages d'en-tête.
  • Un objet JSON dans le corps de la réponse avec des détails supplémentaires qui peuvent vous aider à déterminer comment gérer l'erreur.

Les applications Google Drive doivent détecter et gérer toutes les erreurs pouvant survenir lors de l'utilisation de l'API REST. Ce guide fournit des instructions pour résoudre des erreurs spécifiques de l'API Drive.

Récapitulatif des codes d'état HTTP

Code d'erreur Description
200 - OK La requête aboutit (il s'agit de la réponse standard pour les requêtes HTTP réussies).
400 - Bad Request Impossible de répondre à la requête en raison d'une erreur du client.
401 - Unauthorized La requête contient des identifiants non valides.
403 - Forbidden La requête a été reçue et comprise, mais l'utilisateur n'est pas autorisé à l'exécuter.
404 - Not Found Impossible de trouver la page demandée.
429 - Too Many Requests Trop de requêtes adressées à l'API.
500, 502, 503, 504 - Server Errors Une erreur inattendue se produit lors du traitement de la requête.

Erreurs 400

Ces erreurs signifient que la requête n'était pas acceptable, souvent en raison de l'absence d'un paramètre requis.

badRequest

Cette erreur peut être due à l'un des problèmes suivants dans votre code:

  • Un champ ou un paramètre obligatoire n'a pas été renseigné.
  • La valeur indiquée ou une combinaison de champs indiqués n'est pas valide.
  • Vous avez essayé d'ajouter un parent en double à un fichier Drive.
  • Vous avez essayé d'ajouter un parent qui créerait un cycle dans le graphique de répertoires.

L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

Pour corriger cette erreur, vérifiez le champ message et ajustez votre code en conséquence.

invalidSharingRequest

Cette erreur peut se produire pour plusieurs raisons. Pour déterminer la cause, évaluez le champ reason du fichier JSON renvoyé. Cette erreur se produit le plus souvent pour les raisons suivantes:

  • Le partage a bien été effectué, mais l'e-mail de notification n'a pas été correctement distribué.
  • La modification de la liste de contrôle d'accès (LCA) n'est pas autorisée pour cet utilisateur.

Le champ message indique l'erreur réelle.

Le partage a bien été effectué, mais l'e-mail de notification n'a pas été distribué correctement

L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"Sorry, the items were successfully shared but emails could not be sent to email@domain.com.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

Pour corriger cette erreur, informez l'utilisateur (le partageur) qu'il n'a pas pu effectuer de partage, car l'e-mail de notification n'a pas pu être envoyé à l'adresse e-mail de destination. L'utilisateur doit s'assurer de disposer de la bonne adresse e-mail et s'assurer qu'il peut recevoir des e-mails.

La modification de la LCA n'est pas autorisée pour cet utilisateur

L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"ACL change not allowed.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

Pour corriger cette erreur, vérifiez les paramètres de partage du domaine Google Workspace auquel appartient le fichier. Les paramètres peuvent interdire le partage en dehors du domaine ou le partage d'un Drive partagé peut ne pas être autorisé.

Erreurs 401

Ces erreurs signifient que la requête ne contient pas de jeton d'accès valide.

authError

Cette erreur se produit lorsque le jeton d'accès que vous utilisez a expiré ou n'est pas valide. Cette erreur peut également être due à un manque d'autorisation pour les champs d'application demandés. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

Pour corriger cette erreur, actualisez le jeton d'accès à l'aide du jeton d'actualisation de longue durée. Si cette opération échoue, redirigez l'utilisateur via le flux OAuth, comme décrit dans Choisir des champs d'application d'API Google Drive.

Erreurs 403

Ces erreurs signifient qu'une limite d'utilisation a été dépassée ou que l'utilisateur ne dispose pas des droits appropriés. Pour déterminer la cause, évaluez le champ reason du fichier JSON renvoyé.

Pour en savoir plus sur les limites de l'API Drive, consultez Limites d'utilisation. Pour en savoir plus sur les limites applicables aux dossiers Drive, consultez Limites applicables aux fichiers et aux dossiers.

activeItemCreationLimitExceeded

Une erreur activeItemCreationLimitExceeded se produit lorsque le nombre maximal d'éléments créés par compte est dépassé. Chaque utilisateur peut créer jusqu'à 500 millions d'éléments par compte. Pour en savoir plus, consultez la section Limite par élément utilisateur.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "activeItemCreationLimitExceeded",
    "message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
   }
  ],
  "code": 403,
  "message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
 }
}

Solution :

  1. Informez l'utilisateur que Drive empêche les comptes de créer plus de 500 millions d'éléments.

  2. Si l'utilisateur doit créer des éléments dans le même compte, demandez-lui de les supprimer définitivement. Sinon, il peut utiliser un autre compte qui répond déjà aux exigences.

appNotAuthorizedToFile

Cette erreur se produit lorsque votre application ne figure pas sur la liste de contrôle d'accès associée au fichier. Cette erreur empêche l'utilisateur d'ouvrir le fichier avec votre application. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "appNotAuthorizedToFile",
        "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
  }
}

Pour corriger cette erreur, essayez l'une des solutions suivantes:

  • Ouvrez le sélecteur Google Drive et invitez l'utilisateur à ouvrir le fichier.
  • Demandez à l'utilisateur d'ouvrir le fichier à l'aide du menu contextuel Ouvrir avec de l'interface utilisateur Drive de votre application.
  • Utilisez la méthode files.get pour vérifier le champ isAppAuthorized de la ressource files afin de vérifier que votre application a créé ou ouvert le fichier.

cannotModifyInheritedTeamDrivePermission

Cette erreur se produit lorsqu'un utilisateur tente de modifier les autorisations héritées d'un élément dans un Drive partagé. Les autorisations héritées ne peuvent pas être supprimées d'un élément d'un Drive partagé. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "cannotModifyInheritedTeamDrivePermission",
        "message": "Cannot update or delete an inherited permission on a shared drive item."
      }
    ],
    "code": 403,
    "message": "Cannot update or delete an inherited permission on a shared drive item."
  }
}

Pour corriger cette erreur, un utilisateur doit ajuster les autorisations sur l'élément parent direct ou indirect dont ils ont été hérités. Pour en savoir plus, consultez la section Propagation des autorisations. Vous pouvez également récupérer la ressource permissions.permissionDetails pour voir si les autorisations sur cet élément de Drive partagé sont héritées ou appliquées directement.

dailyLimitExceeded

Cette erreur se produit lorsque la limite d'API pour votre projet est atteinte. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

Cette erreur apparaît lorsque le propriétaire de l'application a défini une limite de quota pour limiter l'utilisation d'une ressource particulière. Pour corriger cette erreur, supprimez tous les plafonds d'utilisation pour le quota "Requêtes par jour".

domainPolicy

Cette erreur se produit lorsque la règle du domaine de l'utilisateur n'autorise pas votre application à accéder à Drive. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Drive apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Drive apps."
  }
}

Solution :

  1. Informez l'utilisateur que le domaine n'autorise pas votre application à accéder aux fichiers dans Drive.
  2. Demandez à l'utilisateur de contacter l'administrateur du domaine pour demander l'accès à votre application.

fileOwnerNotMemberOfTeamDrive

Cette erreur se produit lorsque vous tentez de déplacer un fichier vers un Drive partagé et que le propriétaire du fichier n'en est pas membre. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileOwnerNotMemberOfTeamDrive",
        "message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
      }
    ],
    "code": 403,
    "message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
  }
}

Solution :

  1. Ajoutez le membre au Drive partagé avec role=owner. Pour en savoir plus, consultez Partager des fichiers, des dossiers et des lecteurs.

  2. Ajoutez le fichier au Drive partagé. Pour en savoir plus, consultez la section Créer et renseigner des dossiers.

fileWriterTeamDriveMoveInDisabled

Cette erreur se produit lorsqu'un administrateur de domaine n'a pas autorisé les utilisateurs disposant de role=writer à déplacer des éléments vers un Drive partagé. L'utilisateur qui tente de déplacer les éléments dispose de moins d'autorisations que celles autorisées sur le Drive partagé de destination. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileWriterTeamDriveMoveInDisabled",
        "message": "The domain administrator has not allowed writers to move items into a shared drive."
      }
    ],
    "code": 403,
    "message": "The domain administrator has not allowed writers to move items into a shared drive."
  }
}

Pour corriger cette erreur, utilisez le même compte utilisateur administrateur sur les Drive partagés source et de destination.

insufficientFilePermissions

Cette erreur se produit lorsque l'utilisateur ne dispose pas d'un accès en écriture à un fichier et que votre application tente de le modifier. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "insufficientFilePermissions",
        "message": "The user does not have sufficient permissions for file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user does not have sufficient permissions for file {fileId}."
  }
}

Pour corriger cette erreur, demandez à l'utilisateur de contacter le propriétaire du fichier et de lui demander un accès en modification. Vous pouvez également vérifier les niveaux d'accès des utilisateurs dans les métadonnées récupérées par la méthode files.get et afficher une UI en lecture seule lorsque les autorisations sont manquantes.

myDriveHierarchyDepthLimitExceeded

Une erreur myDriveHierarchyDepthLimitExceeded se produit lorsque la limite du nombre de niveaux de dossiers imbriqués est dépassée. Le dossier Mon Drive d'un utilisateur ne peut pas contenir plus de 100 niveaux de dossiers imbriqués. Pour en savoir plus, consultez la section Limite de profondeur de dossier.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "myDriveHierarchyDepthLimitExceeded",
    "message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/drive/api/guides/handle-errors#nested-folder-levels."
   }
  ],
  "code": 403,
  "message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/drive/api/guides/handle-errors#nested-folder-levels."
 }
}

Solution :

  1. Informez l'utilisateur que Drive ne peut pas placer de dossiers de plus de 100 niveaux.
  2. Si l'utilisateur doit créer un autre dossier imbriqué, demandez-lui de réorganiser le dossier parent prévu pour qu'il comporte moins de 100 niveaux ou d'utiliser un autre dossier parent qui répond déjà aux exigences.

numChildrenInNonRootLimitExceeded

Cette erreur se produit lorsque le nombre maximal d'enfants (dossiers, fichiers et raccourcis) d'un dossier a été dépassé. Le nombre d'éléments pour les dossiers, les fichiers et les raccourcis est limité à 500 000 directement dans un dossier. Les éléments imbriqués dans des sous-dossiers ne sont pas comptabilisés dans cette limite de 500 000 éléments. Pour en savoir plus, consultez la section Limites applicables aux dossiers dans Google Drive.

L'exemple JSON suivant est une représentation de cette erreur:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "numChildrenInNonRootLimitExceeded",
    "message": "The limit for this folder's number of children (files and folders) has been exceeded."
   }
  ],
  "code": 403,
  "message": "The limit for this folder's number of children (files and folders) has been exceeded."
 }
}

Pour corriger cette erreur, essayez l'une des solutions suivantes:

  • Informez l'utilisateur que Drive empêche les dossiers contenant plus de 500 000 éléments.
  • Si l'utilisateur doit ajouter plus d'éléments au dossier complet, demandez-lui de réorganiser le dossier pour y inclure moins de 500 000 éléments ou d'utiliser un dossier similaire contenant déjà moins d'éléments.

rateLimitExceeded

Cette erreur se produit lorsque la limite de débit du projet est atteinte. Cette limite varie en fonction du type de requête. L'exemple JSON suivant est une représentation de cette erreur:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

Pour corriger cette erreur, essayez l'une des solutions suivantes:

sharingRateLimitExceeded

Cette erreur se produit lorsque l'utilisateur atteint une limite de partage et est souvent lié à une limite d'adresses e-mail. L'exemple JSON suivant est une représentation de cette erreur:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "Rate limit exceeded. User message: \"These item(s) could not be shared because a rate limit was exceeded: filename",
    "reason": "sharingRateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

Solution :

  1. N'envoyez pas d'e-mails lorsque vous partagez de grandes quantités de fichiers.
  2. Si un utilisateur effectue de nombreuses requêtes pour le compte de nombreux utilisateurs d'un compte Google Workspace, envisagez d'utiliser un compte de service avec délégation au niveau du domaine à l'aide du paramètre quotaUser.

storageQuotaExceeded

Cette erreur se produit lorsque l'utilisateur atteint sa limite de stockage. L'exemple JSON suivant est une représentation de cette erreur:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "The user's Drive storage quota has been exceeded.",
    "reason": "storageQuotaExceeded",
   }
  ],
  "code": 403,
  "message": "The user's Drive storage quota has been exceeded."
 }
}

Solution :

  1. Vérifiez les limites de stockage de votre compte Drive. Pour en savoir plus, consultez Limites de stockage et d'importation pour Google Workspace.

  2. Gérez les fichiers de votre espace de stockage Google Drive.

  3. Acheter plus d'espace de stockage Google

teamDriveFileLimitExceeded

Cette erreur se produit lorsqu'un utilisateur tente de dépasser la limite stricte d'éléments sur un Drive partagé. Chaque dossier du Drive partagé d'un utilisateur peut contenir jusqu'à 400 000 éléments, fichiers, dossiers et raccourcis inclus. Cette limite est basée sur le nombre d'éléments, et non sur l'utilisation de l'espace de stockage. Pour en savoir plus, consultez Limites des Drive partagés dans Google Drive.

L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveFileLimitExceeded",
        "message": "The file limit for this shared drive has been exceeded."
      }
    ],
    "code": 403,
    "message": "The file limit for this shared drive has been exceeded."
  }
}

Pour corriger cette erreur, réduisez le nombre d'éléments dans le Drive partagé. Les Drive partagés contenant trop de fichiers peuvent être difficiles à organiser et à rechercher.

teamDriveMembershipRequired

Cette erreur se produit lorsqu'un utilisateur tente d'accéder à un Drive partagé dont il n'est pas membre. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveMembershipRequired",
        "message": "The attempted action requires shared drive membership."
      }
    ],
    "code": 403,
    "message": "The attempted action requires shared drive membership."
  }
}

Pour corriger cette erreur, essayez l'une des solutions suivantes:

  1. Demandez au gestionnaire du Drive partagé de vous ajouter avec les autorisations appropriées pour l'action que vous devez effectuer.

  2. Consultez la section Rôles et autorisations de Drive pour savoir qui peut accéder aux Drive partagés et les gérer. Vous trouverez des informations supplémentaires sur les niveaux d'accès dans Créer un Drive partagé.

teamDrivesFolderMoveInNotSupported

Cette erreur se produit lorsqu'un utilisateur tente de déplacer un dossier de Mon Drive vers un Drive partagé. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDrivesFolderMoveInNotSupported",
        "message": "Moving folders into shared drives is not supported."
      }
    ],
    "code": 403,
    "message": "Moving folders into shared drives is not supported."
  }
}

Pour corriger cette erreur, essayez l'une des solutions suivantes:

  • Déplacez les éléments individuels du dossier vers un Drive partagé à l'aide de l'API Drive. Définissez le paramètre supportsAllDrives=true pour indiquer la compatibilité de Mon Drive et des Drive partagés.

  • Si vous devez déplacer le dossier vers un Drive partagé, utilisez l'interface utilisateur de Drive. Pour en savoir plus, consultez Déplacer des dossiers vers des Drive partagés en tant qu'administrateur.

teamDrivesParentLimit

Cette erreur se produit lorsqu'un utilisateur tente d'ajouter plusieurs parents à un élément dans un Drive partagé. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDrivesParentLimit",
        "message": "A shared drive item must have exactly one parent."
      }
    ],
    "code": 403,
    "message": "A shared drive item must have exactly one parent."
  }
}

Pour corriger cette erreur, utilisez les raccourcis Drive pour ajouter plusieurs liens à un fichier. Bien qu'un raccourci ne puisse avoir qu'un seul parent, un fichier de raccourci peut être copié vers les emplacements supplémentaires. Pour en savoir plus, consultez Créer un raccourci vers un fichier Drive.

UrlLeaseLimitExceeded

Cette erreur se produit lorsque vous essayez d'enregistrer des données de jeu Google Play via votre application. L'exemple JSON suivant est une représentation de cette erreur:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "UrlLeaseLimitExceeded",
    "message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
   }
  ],
  "code": 403,
  "message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
 }
}

Pour corriger cette erreur, terminez ou annulez toutes les importations d'un instantané avant d'en créer d'autres.

userRateLimitExceeded

Cette erreur se produit lorsque la limite par utilisateur est atteinte. Il peut s'agir d'une limite de la console Google Cloud ou du backend de Drive. L'exemple JSON suivant est une représentation de cette erreur:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

Pour corriger cette erreur, essayez l'une des solutions suivantes:

Pour en savoir plus sur les limites de l'API Drive, consultez Limites d'utilisation.

Erreurs 404

Ces erreurs signifient que la ressource demandée n'est pas accessible ou n'existe pas.

notFound

Cette erreur se produit lorsque l'utilisateur ne dispose pas d'un accès en lecture à un fichier ou que le fichier n'existe pas. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "File not found {fileId}"
      }
    ],
    "code": 404,
    "message": "File not found: {fileId}"
  }
}

Solution :

  1. Informez l'utilisateur qu'il ne dispose pas d'un accès en lecture au fichier ou que celui-ci n'existe pas.
  2. Demandez à l'utilisateur de contacter le propriétaire du fichier et de lui demander l'autorisation d'y accéder.

Erreurs 429

Ces erreurs signifient que trop de requêtes ont été envoyées trop rapidement à l'API.

rateLimitExceeded

Cette erreur se produit lorsque l'utilisateur a envoyé trop de requêtes dans un laps de temps donné. L'exemple JSON suivant est une représentation de cette erreur:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 429,
    "message": "Rate Limit Exceeded"s
  }
}

Pour corriger cette erreur, utilisez un intervalle exponentiel entre les tentatives pour relancer la requête.

Erreurs 500, 502, 503, 504

Ces erreurs se produisent lorsqu'une erreur de serveur inattendue se produit lors du traitement de la requête. Différents problèmes peuvent être à l'origine de ces erreurs, y compris une demande qui chevauche une autre demande ou une demande concernant une action non acceptée (par exemple, une tentative de mise à jour des autorisations pour une seule page dans Google Sites et non pour l'ensemble du site).

Voici une liste d’erreurs 5xx:

  • Erreur de backend 500
  • 502 Passerelle incorrecte
  • 503 Service indisponible.
  • 504 Expiration du délai de la passerelle

Pour corriger cette erreur, utilisez un intervalle exponentiel entre les tentatives pour relancer la requête.