Resuelve los errores

La API de Google Drive devuelve dos niveles de información sobre el 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 controlar el error.

Las apps para Google Drive deben detectar y controlar todos los errores que pueden surgir cuando usas la API de REST. En esta guía, se proporcionan instrucciones para resolver errores específicos de la API de Drive.

Resumen de los códigos de estado HTTP

Código de error Descripción
200 - OK La solicitud se realizó correctamente (esta es la respuesta estándar para las solicitudes HTTP correctas).
400 - Bad Request No se puede completar la solicitud debido a un error del cliente.
401 - Unauthorized La solicitud contiene credenciales no válidas.
403 - Forbidden Se recibió y se entendió 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 Se realizaron demasiadas solicitudes a la API.
500, 502, 503, 504 - Server Errors Se produce un error inesperado mientras se procesa la solicitud.

Errores 400

Estos errores indican que la solicitud no fue aceptable, a menudo debido a la falta de 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 elemento superior duplicado a un archivo de Drive.
  • Intentaste agregar un elemento superior que crearía un ciclo en el gráfico de directorio.

El siguiente ejemplo 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 el código según corresponda.

invalidSharingRequest

Este error ocurre 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:

  • El uso compartido se realizó correctamente, pero la notificación por correo electrónico no se entregó correctamente.
  • No se permite el cambio de la lista de control de acceso (LCA) para este usuario.

El campo message indica el error real.

Se compartió el contenido correctamente, pero el correo electrónico de notificación no se entregó de forma correcta

El siguiente ejemplo 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, infórmale al usuario (persona que comparte) que no pudo realizar el uso compartido 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

El siguiente ejemplo 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 compartir elementos 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 usas está vencido o no es válido. Este error también puede deberse a que falta la autorización para los permisos solicitados. El siguiente ejemplo 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 por el flujo de OAuth, como se describe en Elige los permisos de la API de Google Drive.

fileNotDownloadable

Este error ocurre cuando intentas usar el método revisions.get con el parámetro de URL alt=media en un documento de Google Workspace. El siguiente ejemplo de JSON es una representación de este error:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileNotDownloadable",
        "message": "Only files with binary content can be downloaded. Use Export with Docs Editors files."
      }
    ],
    "code": 403,
    "message": "Only files with binary content can be downloaded. Use Export with Docs Editors files."
  }
}

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

  • Quita el parámetro de URL alt=media si deseas ver los metadatos de una revisión en particular, como el tipo de MIME.
  • Usa el método files.export para exportar el contenido de bytes de los documentos de Google Workspace. Para obtener más información, consulta Cómo exportar el contenido de un documento de Google Workspace.

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. Para obtener 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 la cantidad 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 por 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. Infórmale al usuario que Drive impide 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 elimine algunos objetos de forma permanente. De lo contrario, puede usar una cuenta diferente que ya cumpla con el requisito.

appNotAuthorizedToFile

Este error se produce cuando tu app 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 usando el menú contextual Abrir con en la IU de Drive de tu app.
  • Usa el método files.get para verificar el campo isAppAuthorized en el recurso files y comprobar que 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 en una unidad compartida. El siguiente ejemplo 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, el usuario debe ajustar los permisos del 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 ocurre cuando se alcanza el límite de la API de tu proyecto. El siguiente ejemplo 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 estableció un límite de cuota para limitar 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 los archivos de Drive.
  2. Pídele al usuario que se comunique con el administrador del 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. El siguiente ejemplo 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 Crea y propaga 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. El siguiente ejemplo 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 de 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, pídele 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 falten permisos.

myDriveHierarchyDepthLimitExceeded

Se produce un error myDriveHierarchyDepthLimitExceeded cuando se supera el límite de la cantidad de niveles de carpetas anidadas. 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. Infórmale al usuario que Drive impide colocar carpetas con más de 100 niveles de profundidad.
  2. Si el usuario debe crear otra carpeta anidada, pídele que reorganice la carpeta superior para que tenga menos de 100 niveles de profundidad 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 de una carpeta (carpetas, archivos y accesos directos). Existe 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 en Google Drive.

El siguiente ejemplo 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 que se creen carpetas con más de 500,000 elementos.
  • Si el usuario debe agregar más elementos a la carpeta completa, pídele que reorganice la carpeta para que contenga menos de 500,000 elementos o que use una carpeta similar que ya contenga menos elementos.

rateLimitExceeded

Este error ocurre cuando se alcanza el límite de frecuencia del proyecto. Este límite varía según el tipo de solicitud. El siguiente ejemplo 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. El siguiente ejemplo 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 varios usuarios de una cuenta de Google Workspace, considera usar una cuenta de servicio con delegación de todo el dominio que use el parámetro quotaUser.

storageQuotaExceeded

Este error se produce 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 de 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 en Google Drive.

  3. Compra más almacenamiento de Google.

teamDriveFileLimitExceeded

Este error se produce 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 500,000 elementos, incluidos archivos, carpetas y accesos directos. Este límite se basa en la cantidad de artículos, no en el uso del almacenamiento. Para obtener más información, consulta Límites de unidades compartidas en Google Drive.

El siguiente ejemplo 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. Las unidades compartidas con demasiados archivos pueden ser difíciles de organizar y buscar.

teamDriveHierarchyTooDeep

Se produce un error teamDriveHierarchyTooDeep cuando se supera el límite de la cantidad de niveles de carpetas anidadas de la unidad compartida. La unidad compartida 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": "teamDriveHierarchyTooDeep",
    "message": "The shared drive hierarchy depth will exceed the limit."
   }
  ],
  "code": 403,
  "message": "The shared drive hierarchy depth will exceed the limit."
 }
}

Para corregir este error:

  1. Informa al usuario que las unidades compartidas evitan que se coloquen 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 prevista para que tenga menos de 100 niveles o use una carpeta superior diferente que ya cumpla con el requisito.

teamDriveMembershipRequired

Este error se produce cuando un usuario intenta acceder a una unidad compartida de la que no es miembro. El siguiente ejemplo 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 con los permisos adecuados para la acción que debes realizar.

  2. Revisa los roles 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 Cómo crear una unidad compartida.

teamDrivesFolderMoveInNotSupported

Este error se produce 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:

  • Mueve 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 Cómo mover carpetas a unidades compartidas como administrador.

teamDrivesParentLimit

Este error se produce cuando un usuario intenta agregar más de un elemento superior a un elemento en una unidad compartida. El siguiente ejemplo 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."
  }
}

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

UrlLeaseLimitExceeded

Este error se produce cuando se intenta guardar datos del juego de Google Play a través de tu aplicación. El siguiente ejemplo 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. El siguiente ejemplo 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 que no existe.

notFound

Este error se produce cuando el usuario no tiene acceso de lectura a un archivo o cuando este no existe. El siguiente ejemplo 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. Si el archivo se encuentra en una unidad compartida y usas el método files.get, asegúrate de que el parámetro de consulta supportsAllDrives esté configurado como true.
  2. Informa al usuario que no tiene acceso de lectura al archivo o que el archivo no existe.
  3. Pídele al usuario que se comunique con el propietario del archivo y solicite permiso para acceder a él.

Errores 429

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

rateLimitExceeded

Este error ocurre cuando el usuario envió demasiadas solicitudes en un período determinado. El siguiente ejemplo 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 para reintentar la solicitud.

Errores 500, 502, 503 y 504

Estos errores ocurren cuando se produce un error inesperado del servidor mientras se procesa la solicitud. Varios problemas pueden causar estos errores, como que el tiempo de una solicitud se superponga con otra solicitud o que se solicite una acción no admitida, como intentar 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

Si quieres corregir este error, usa la retirada exponencial para reintentar la solicitud.