Corriger les erreurs

L'API Google Drive renvoie deux niveaux d'informations sur les erreurs:

  • Codes d'erreur HTTP et messages d'en-tête
  • Objet JSON dans le corps de la réponse, avec des informations 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 qui peuvent se produire lors de l'utilisation de l'API REST. Ce guide explique comment résoudre des erreurs spécifiques de l'API Drive.

Résumé du code 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 qui aboutissent).
400 - Bad Request Impossible de traiter 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 d'un paramètre obligatoire manquant.

badRequest

Cette erreur peut se produire pour l'un des problèmes suivants dans votre code:

  • Un champ ou un paramètre obligatoire n'a pas été renseigné.
  • La valeur fournie ou une combinaison de champs fournis 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 du répertoire.

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 se produit 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 réussi, mais l'e-mail de notification n'a pas été distribué correctement.
  • 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é envoyé 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 (partageur) qu'il n'a pas pu partager, car l'e-mail de notification n'a pas pu être envoyé à l'adresse e-mail de destination. L'utilisateur doit s'assurer qu'il dispose de la bonne adresse e-mail et 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 à une autorisation manquante 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. En cas d'échec, redirigez l'utilisateur via le flux OAuth, comme décrit dans la section Choisir les champs d'application des 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 des dossiers Drive, consultez Limites des fichiers et des dossiers.

activeItemCreationLimitExceeded

Une erreur activeItemCreationLimitExceeded se produit lorsque la limite du nombre d'éléments créés par compte a été dépassée. Chaque utilisateur peut avoir jusqu'à 500 millions d'éléments créés par un compte. Pour en savoir plus, consultez la section Limite d'é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 ce même compte, demandez-lui de supprimer définitivement certains objets. Sinon, il peut utiliser un autre compte qui répond déjà à cette exigence.

appNotAuthorizedToFile

Cette erreur se produit lorsque votre application ne figure pas dans la LCA du fichier. Cette erreur empêche l'utilisateur d'ouvrir le fichier avec votre application. L'exemple JSON suivant illustre 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 l'outil de sélection Google Drive et invitez l'utilisateur à ouvrir le fichier.
  • Demandez à l'utilisateur d'ouvrir le fichier à l'aide du menu contextuel Ouvrir avec dans l'interface utilisateur Drive de votre application.
  • Utilisez la méthode files.get pour vérifier le champ isAppAuthorized de la ressource files et vous assurer 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 d'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 modifier les autorisations de l'élément parent direct ou indirect dont il a hérité. 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 du Drive partagé sont héritées ou appliquées directement.

dailyLimitExceeded

Cette erreur se produit lorsque la limite d'API pour votre projet a été 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 les limites d'utilisation du quota "Requêtes par jour".

domainPolicy

Cette erreur se produit lorsque la règle associée au domaine de l'utilisateur n'autorise pas votre application à accéder à Drive. L'exemple JSON suivant illustre 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é dont le propriétaire n'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 remplir 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 pour 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 a été 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 empêche de placer des dossiers à plus de 100 niveaux de profondeur.
  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à à cette exigence.

numChildrenInNonRootLimitExceeded

Cette erreur se produit lorsque la limite du nombre d'enfants (dossiers, fichiers et raccourcis) d'un dossier a été dépassée. Les dossiers, fichiers et raccourcis directement dans un dossier sont limités à 500 000 éléments. Les éléments imbriqués dans des sous-dossiers ne sont pas pris en compte dans cette limite de 500 000 éléments. Pour en savoir plus sur les limites applicables aux dossiers Drive, consultez Limites des 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 qu'il en contienne moins de 500 000 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 a été 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 qu'il est souvent associé à 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 envoie de nombreuses requêtes au nom de plusieurs 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 dans Google Workspace.

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

  3. Achetez de l'espace de stockage Google supplémentaire.

teamDriveFileLimitExceeded

Cette erreur se produit lorsqu'un utilisateur tente de dépasser la limite stricte d'éléments dans un Drive partagé. Chaque dossier du Drive partagé d'un utilisateur est limité à 500 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 comportant 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 à effectuer.

  2. Consultez la page Rôles et autorisations de Drive pour savoir qui peut accéder aux Drive partagés et les gérer. Vous trouverez également 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éplacer 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 d'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, ajoutez plusieurs liens à un fichier à l'aide des raccourcis Drive. Bien qu'un raccourci ne puisse avoir qu'un seul parent, un fichier de raccourci peut être copié dans 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 a été atteinte. Il peut s'agir d'une limite provenant de la console Google Cloud ou du backend 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 lorsque 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. Si le fichier se trouve dans un Drive partagé et que vous utilisez la méthode files.get, assurez-vous que le paramètre de requête supportsAllDrives est défini sur true.
  2. Informez l'utilisateur qu'il ne dispose pas d'un accès en lecture au fichier ou que le fichier n'existe pas.
  3. 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 à l'API trop rapidement.

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, appliquez un intervalle exponentiel entre les tentatives afin de relancer la requête.

Erreurs 500, 502, 503, 504

Ces erreurs se produisent lorsqu'une erreur inattendue du serveur se produit lors du traitement de la requête. Différents problèmes peuvent être à l'origine de ces erreurs. Il peut s'agir, par exemple, d'un chevauchement du délai d'une requête avec celui d'une autre, ou d'une demande d'action non acceptée (par exemple, une tentative de mise à jour des autorisations pour une seule page de Google Sites plutôt que pour l'ensemble du site).

Voici une liste d'erreurs 5xx:

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

Pour corriger cette erreur, appliquez un intervalle exponentiel entre les tentatives afin de relancer la requête.