La API de Google Drive muestra dos niveles de información de error:
- Códigos de error 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 de Google Drive deben detectar y controlar todos los errores que puedan ocurrir 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 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 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 |
Se realizaron 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 indican que la solicitud no se pudo aceptar, a menudo debido a que falta 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 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:
- El contenido se compartió correctamente, pero el correo electrónico de notificación 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 compartir el archivo 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.
No se permite el cambio de la LCA 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, verifica 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=mediasi deseas ver los metadatos de una revisión en particular, como el tipo de MIME. - Usa el método
files.exportpara 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:
Infórmale al usuario que Drive impide que las cuentas creen más de 500 millones de elementos.
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.
- Indícale al usuario que abra el archivo con el menú contextual Abrir con en la IU de Drive de tu app.
- Usa el método
files.getpara verificar el campoisAppAuthorizeden el recursofilesy 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 de 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:
- Informa al usuario que el dominio no permite que tu app acceda a los archivos de Drive.
- 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:
Agrega al miembro a la unidad compartida con
role=owner. Para obtener más información, consulta Cómo compartir archivos, carpetas y unidades.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:
- Infórmale al usuario que Drive impide colocar carpetas con más de 100 niveles de profundidad.
- 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 tienen en cuenta en 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 la reorganize para que contenga 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:
- Aumenta la cuota por usuario en el proyecto de Google Cloud. Para obtener más información, solicita un aumento de la cuota.
- Solicitudes por lotes para agrupar varias llamadas a la API en una solicitud HTTP.
- Usa la retirada exponencial para reintentar la solicitud.
sharingRateLimitExceeded
Este error se produce 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:
- No envíes correos electrónicos cuando compartas grandes cantidades de archivos.
- Si un usuario realiza varias solicitudes en nombre de muchos usuarios de una cuenta de Google Workspace, considera usar una cuenta de servicio con delegación de todo el dominio con el parámetro
quotaUser.
storageQuotaExceeded
Este error se produce cuando el usuario alcanza su límite de almacenamiento. El siguiente ejemplo 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:
Revisa los límites de almacenamiento de tu cuenta de Drive. Para obtener más información, consulta los límites de almacenamiento y cargas de Google Workspace.
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 las 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:
- Infórmale al usuario que las unidades compartidas impiden colocar carpetas con más de 100 niveles de anidación.
- 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.
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:
Pídele al administrador de la unidad compartida que te agregue con los permisos adecuados para la acción que debes realizar.
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=truepara 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."
}
}
Para corregir este error, usa los atajos 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 ocurre cuando se intentan guardar datos de juegos 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:
Aumenta la cuota por usuario en el proyecto de Google Cloud. Para obtener más información, solicita un aumento de la cuota.
Si un usuario realiza varias solicitudes en nombre de muchos usuarios de una cuenta de Google Workspace, considera usar una cuenta de servicio con delegación de todo el dominio con el parámetro
quotaUser.Usa la retirada exponencial para reintentar la solicitud.
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:
- Si el archivo se encuentra en una unidad compartida y usas el método
files.get, asegúrate de que el parámetro de consultasupportsAllDrivesesté configurado comotrue. - Informa al usuario que no tiene acceso de lectura al archivo o que este no existe.
- Pídele al usuario que se comunique con el propietario del archivo y solicite permiso para acceder a él.
Errores 429
Estos errores significan 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 se producen cuando surge 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 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
Para corregir este error, usa la retirada exponencial para reintentar la solicitud.