Resuelve los errores

La API de Google Drive devuelve dos niveles de información de error:

  • Códigos de error de HTTP y mensajes de encabezado
  • Un objeto JSON en el cuerpo de la respuesta con detalles adicionales que pueden ayudarte a determinar cómo manejar el error

Las apps de Google Drive deben detectar y manejar todos los errores que se puedan encontrar cuando se usa la API de REST. En esta guía, se proporcionan instrucciones para resolver errores específicos de la API de Drive.

Resumen del código de estado HTTP

Código de error Descripción
200 - OK La solicitud se realiza correctamente (esta es la respuesta estándar para las solicitudes HTTP exitosas).
400 - Bad Request No se puede completar la solicitud debido a un error del cliente en la solicitud.
401 - Unauthorized La solicitud contiene credenciales no válidas.
403 - Forbidden Se recibió y comprendió la solicitud, pero el usuario no tiene permiso para realizarla.
404 - Not Found No se pudo encontrar la página solicitada.
429 - Too Many Requests Demasiadas solicitudes a la API.
500, 502, 503, 504 - Server Errors Se produce un error inesperado cuando se procesa la solicitud.

Errores 400

Estos errores significan que la solicitud no fue aceptable, a menudo debido a que faltaba un parámetro obligatorio.

badRequest

Este error puede ocurrir por cualquiera de los siguientes problemas en tu código:

  • No se proporcionó un campo o parámetro obligatorio.
  • El valor proporcionado o una combinación de campos proporcionados no es válido.
  • Intentaste agregar un padre duplicado a un archivo de Drive.
  • Intentaste agregar un elemento superior que crearía un ciclo en el gráfico del directorio.

La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error, revisa el campo message y ajusta tu código según corresponda.

invalidSharingRequest

Este error se produce por varios motivos. Para determinar la causa, evalúa el campo reason del JSON que se muestra. Este error suele ocurrir por los siguientes motivos:

  • Se compartió correctamente, pero la notificación por correo electrónico no se entregó correctamente.
  • El cambio de la lista de control de acceso (LCA) no está permitido para este usuario.

El campo message indica el error real.

Se compartió correctamente, pero la notificación por correo electrónico no se entregó correctamente

La siguiente muestra de JSON es una representación de este error:

{
  "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"
  }
}

Para corregir este error, informa al usuario (usuario que comparte datos) que no pudo compartir porque el correo electrónico de notificación no se pudo enviar a la dirección de correo electrónico de destino. El usuario debe asegurarse de tener la dirección de correo electrónico correcta y de que pueda recibir correos electrónicos.

El cambio de LCA no está permitido para este usuario

La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, consulta la configuración de uso compartido del dominio de Google Workspace al que pertenece el archivo. Es posible que la configuración prohíba el uso compartido fuera del dominio o que no se permita compartir una unidad compartida.

Errores 401

Estos errores significan que la solicitud no contiene un token de acceso válido.

authError

Este error se produce cuando el token de acceso que estás usando está vencido o no es válido. Este error también puede deberse a la falta de autorización para los permisos solicitados. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, actualiza el token de acceso con el token de actualización de larga duración. Si esto falla, dirige al usuario a través del flujo de OAuth, como se describe en Cómo elegir los permisos de la API de Google Drive.

Errores 403

Estos errores significan que se superó un límite de uso o que el usuario no tiene los privilegios correctos. Para determinar la causa, evalúa el campo reason del JSON que se muestra.

Para obtener información sobre los límites de la API de Drive, consulta Límites de uso. Si quieres obtener más información sobre los límites de las carpetas de Drive, consulta Límites de archivos y carpetas.

activeItemCreationLimitExceeded

Se produce un error activeItemCreationLimitExceeded cuando se supera el límite de elementos creados por cuenta. Cada usuario puede tener hasta 500 millones de elementos creados por una cuenta. Para obtener más información, consulta Límite de elementos de usuario.

{
 "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."
 }
}

Para corregir este error:

  1. Informa al usuario que Drive evita que las cuentas creen más de 500 millones de elementos.

  2. Si el usuario debe crear elementos en esta misma cuenta, indícale que borre de forma permanente algunos objetos. De lo contrario, puede usar una cuenta diferente que ya cumpla con el requisito.

appNotAuthorizedToFile

Este error ocurre cuando tu aplicación no está en la LCA del archivo. Este error impide que el usuario abra el archivo con tu app. El siguiente ejemplo de JSON es una representación de este error:

{
  "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}."
  }
}

Para corregir este error, prueba alguna de las siguientes opciones:

  • Abre el selector de Google Drive y pídele al usuario que abra el archivo.
  • Indica al usuario que abra el archivo desde el menú contextual Abrir con en la IU de Drive de tu app.
  • Usa el método files.get para verificar el campo isAppAuthorized del recurso files y verificar si tu app creó o abrió el archivo.

cannotModifyInheritedTeamDrivePermission

Este error se produce cuando un usuario intenta modificar los permisos heredados de un elemento dentro de una unidad compartida. No se pueden quitar los permisos heredados de un elemento de una unidad compartida. La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error, un usuario debe ajustar los permisos en el elemento superior directo o indirecto del que se heredaron. Para obtener más información, consulta Propagación de permisos. También puedes recuperar el recurso permissions.permissionDetails para ver si los permisos de este elemento de la unidad compartida se heredan o se aplican directamente.

dailyLimitExceeded

Este error se produce cuando se alcanza el límite de la API de tu proyecto. La siguiente muestra de JSON es una representación de este error:

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

Este error aparece cuando el propietario de la aplicación establece un límite de cuota para restringir el uso de un recurso en particular. Para corregir este error, quita cualquier límite de uso de la cuota “Consultas por día”.

domainPolicy

Este error se produce cuando la política del dominio del usuario no permite que tu app acceda a Drive. El siguiente ejemplo de JSON es una representación de este error:

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

Para corregir este error:

  1. Informa al usuario que el dominio no permite que tu app acceda a archivos de Drive.
  2. Indica al usuario que se comunique con el administrador de dominio para solicitar acceso a tu app.

fileOwnerNotMemberOfTeamDrive

Este error ocurre cuando se intenta mover un archivo a una unidad compartida y el propietario del archivo no es miembro. La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error:

  1. Agrega al miembro a la unidad compartida con role=owner. Para obtener más información, consulta Cómo compartir archivos, carpetas y unidades.

  2. Agrega el archivo a la unidad compartida. Para obtener más información, consulta Cómo crear y propagar carpetas.

fileWriterTeamDriveMoveInDisabled

Este error se produce cuando un administrador de dominio no permitió que los usuarios con role=writer muevan elementos a una unidad compartida. El usuario que intenta mover los elementos tiene menos permisos de los permitidos en la unidad compartida de destino. La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error, usa la misma cuenta de usuario de administrador en las unidades compartidas de origen y destino.

insufficientFilePermissions

Este error se produce cuando el usuario no tiene acceso de escritura a un archivo y tu app intenta modificarlo. La siguiente muestra de JSON es una representación de este error:

{
  "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}."
  }
}

Para corregir este error, indica al usuario que se comunique con el propietario del archivo y solicite acceso de edición. También puedes verificar los niveles de acceso de los usuarios en los metadatos que recupera el método files.get y mostrar una IU de solo lectura cuando faltan permisos.

myDriveHierarchyDepthLimitExceeded

Se produce un error myDriveHierarchyDepthLimitExceeded cuando se supera el límite de niveles de carpetas anidadas. La sección Mi unidad de un usuario no puede contener más de 100 niveles de carpetas anidadas. Para obtener más información, consulta Límite de profundidad de carpetas.

{
 "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."
 }
}

Para corregir este error:

  1. Informa al usuario que Drive no permite colocar carpetas con más de 100 niveles de profundidad.
  2. Si el usuario debe crear otra carpeta anidada, indícale que reorganice la carpeta superior deseada para que tenga menos de 100 niveles o que use una carpeta superior diferente que ya cumpla con el requisito.

numChildrenInNonRootLimitExceeded

Este error ocurre cuando se supera el límite de la cantidad de elementos secundarios (carpetas, archivos y accesos directos) de una carpeta. Hay un límite de 500,000 elementos para las carpetas, los archivos y los accesos directos directamente en una carpeta. Los elementos anidados en subcarpetas no se descuentan de este límite de 500,000 elementos. Para obtener más información sobre los límites de las carpetas de Drive, consulta Límites de las carpetas de Google Drive.

La siguiente muestra de JSON es una representación de este error:

{
 "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."
 }
}

Para corregir este error, prueba alguna de las siguientes opciones:

  • Informa al usuario que Drive impide el uso de carpetas con más de 500,000 elementos.
  • Si el usuario debe agregar más elementos a la carpeta completa, indícale que la reorganice para contener menos de 500,000 elementos o que use una carpeta similar que ya contenga menos elementos.

rateLimitExceeded

Este error se produce cuando se alcanza el límite de frecuencia del proyecto. Este límite varía según el tipo de solicitud. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, prueba alguna de las siguientes opciones:

sharingRateLimitExceeded

Este error ocurre cuando el usuario alcanza un límite de uso compartido y, a menudo, se vincula con un límite de correo electrónico. La siguiente muestra de JSON es una representación de este error:

{
 "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"
 }
}

Para corregir este error:

  1. No envíes correos electrónicos cuando compartas grandes cantidades de archivos.
  2. Si un usuario realiza varias solicitudes en nombre de muchos usuarios de una cuenta de Google Workspace, considera utilizar una cuenta de servicio con delegación de todo el dominio mediante el parámetro quotaUser.

storageQuotaExceeded

Este error ocurre cuando el usuario alcanza su límite de almacenamiento. La siguiente muestra de JSON es una representación de este error:

{
 "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."
 }
}

Para corregir este error:

  1. Revisa los límites de almacenamiento en tu cuenta de Drive. Para obtener más información, consulta Límites de almacenamiento y carga de Google Workspace.

  2. Administra archivos en tu almacenamiento de Google Drive.

  3. Compra más almacenamiento de Google.

teamDriveFileLimitExceeded

Este error ocurre cuando un usuario intenta exceder el límite estricto de elementos en una unidad compartida. Cada carpeta de la unidad compartida de un usuario tiene un límite de 400,000 elementos, incluidos archivos, carpetas y accesos directos. Este límite se basa en la cantidad de elementos, no en el uso de almacenamiento. Para obtener más información, consulta Límites de unidades compartidas en Google Drive.

La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error, reduce la cantidad de elementos en la unidad compartida. Es posible que las unidades compartidas con demasiados archivos sean difíciles de organizar y buscar.

teamDriveMembershipRequired

Este error ocurre cuando un usuario intenta acceder a una unidad compartida de la que no es miembro. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, prueba alguna de las siguientes opciones:

  1. Pídele al administrador de la unidad compartida que te agregue los permisos adecuados para la acción que debes realizar.

  2. Revisa las funciones y permisos de Drive para saber quién puede acceder a las unidades compartidas y administrarlas. También puedes encontrar información adicional sobre los niveles de acceso en Crea una unidad compartida.

teamDrivesFolderMoveInNotSupported

Este error ocurre cuando un usuario intenta mover una carpeta de Mi unidad a una unidad compartida. La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error, prueba alguna de las siguientes opciones:

  • Mover los elementos individuales de la carpeta a una unidad compartida con la API de Drive Establece el parámetro supportsAllDrives=true para indicar la compatibilidad con Mi unidad y las unidades compartidas.

  • Si debes mover la carpeta a una unidad compartida, usa la IU de Drive. Para obtener más información, consulta Mueve carpetas a unidades compartidas como administrador.

teamDrivesParentLimit

Este error ocurre cuando un usuario intenta agregar más de un elemento superior a un elemento de una unidad compartida. La siguiente muestra de JSON es una representación de este error:

{
  "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."
  }
}

Para corregir este error, usa accesos directos de Drive para agregar varios vínculos a un archivo. Aunque un acceso directo solo puede tener un elemento superior, un archivo de acceso directo se puede copiar en las ubicaciones adicionales. Para obtener más información, consulta Cómo crear un acceso directo a un archivo de Drive.

UrlLeaseLimitExceeded

Este error se produce cuando intentas guardar datos de juegos de Google Play a través de tu aplicación. La siguiente muestra de JSON es una representación de este error:

{
 "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."
 }
}

Para corregir este error, completa o cancela las cargas de una instantánea antes de crear más.

userRateLimitExceeded

Este error se produce cuando se alcanza el límite por usuario. Puede ser un límite de la consola de Google Cloud o un límite del backend de Drive. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, prueba alguna de las siguientes opciones:

Para obtener información sobre los límites de la API de Drive, consulta Límites de uso.

Errores 404

Estos errores significan que no se puede acceder al recurso solicitado o no existe.

notFound

Este error ocurre cuando el usuario no tiene acceso de lectura a un archivo o el archivo no existe. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error:

  1. Informa al usuario que no tiene acceso de lectura al archivo o que este no existe.
  2. Indica al usuario que se comunique con el propietario del archivo y le solicite permiso.

Errores 429

Estos errores significan que se enviaron demasiadas solicitudes a la API demasiado rápido.

rateLimitExceeded

Este error se produce cuando el usuario envía demasiadas solicitudes en un período determinado. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, usa la retirada exponencial y reintenta la solicitud.

Errores 500, 502, 503 y 504

Estos errores se producen cuando se produce un error de servidor inesperado mientras se procesa la solicitud. Varios problemas pueden causar estos errores, por ejemplo, cuando una solicitud se superpone con otra o la solicitud por una acción no compatible, como cuando se intenta actualizar los permisos de una sola página en Google Sites en lugar de todo el sitio.

La siguiente es una lista de errores 5xx:

  • Error de backend 500
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Para corregir este error, usa la retirada exponencial y reintenta la solicitud.