corrigir erros.

A API Google Drive retorna dois níveis de informações de erro:

  • Códigos de erro HTTP e mensagens de cabeçalho.
  • Um objeto JSON no corpo da resposta com mais detalhes que podem ajudar a determinar como lidar com o erro.

Os aplicativos do Google Drive precisam capturar e processar todos os erros que podem ser encontrados ao usar a API REST. Este guia fornece instruções sobre como resolver erros específicos da API Drive.

Resumo do código de status HTTP

Código do erro Descrição
200 - OK A solicitação foi concluída. Essa é a resposta padrão para solicitações HTTP bem-sucedidas.
400 - Bad Request Não foi possível atender à solicitação devido a um erro de cliente.
401 - Unauthorized A solicitação contém credenciais inválidas.
403 - Forbidden A solicitação foi recebida e compreendida, mas o usuário não tem permissão para executá-la.
404 - Not Found Não foi possível encontrar a página solicitada.
429 - Too Many Requests Muitas solicitações à API.
500, 502, 503, 504 - Server Errors Ocorre um erro inesperado ao processar a solicitação.

Erros 400

Esses erros significam que a solicitação não foi aceita, geralmente devido a um parâmetro obrigatório ausente.

badRequest

Esse erro pode ocorrer por um dos seguintes problemas no código:

  • Um campo ou parâmetro obrigatório não foi fornecido.
  • O valor fornecido ou uma combinação de campos fornecidos é inválido.
  • Você tentou adicionar um pai duplicado a um arquivo do Drive.
  • Você tentou adicionar um pai que criaria um ciclo no gráfico de diretório.

O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, verifique o campo message e ajuste o código de forma adequada.

invalidSharingRequest

Esse erro ocorre por vários motivos. Para determinar a causa, avalie o campo reason do JSON retornado. Esse erro geralmente ocorre porque:

  • O compartilhamento foi concluído, mas o e-mail de notificação não foi entregue corretamente.
  • A mudança na lista de controle de acesso (ACL) não é permitida para esse usuário.

O campo message indica o erro real.

A ação de compartilhamento foi concluída, mas o e-mail de notificação não foi entregue corretamente

O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, informe ao usuário (compartilhador) que ele não conseguiu compartilhar porque o e-mail de notificação não foi enviado para o endereço de e-mail de destino. O usuário precisa ter certeza de que tem o endereço de e-mail correto e que ele pode receber e-mails.

A mudança de ACL não é permitida para este usuário

O exemplo de JSON a seguir é uma representação desse erro:

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

Para corrigir esse erro, verifique as configurações de compartilhamento do domínio do Google Workspace ao qual o arquivo pertence. As configurações podem proibir o compartilhamento fora do domínio, ou o compartilhamento de um drive compartilhado pode não ser permitido.

Erros 401

Esses erros significam que a solicitação não contém um token de acesso válido.

authError

Esse erro ocorre quando o token de acesso que você está usando está expirado ou inválido. Esse erro também pode ser causado pela falta de autorização para os escopos solicitados. O exemplo de JSON a seguir é uma representação desse erro:

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

Para corrigir esse erro, atualize o token de acesso usando o token de atualização de longa duração. Se isso falhar, direcione o usuário pelo fluxo OAuth, conforme descrito em Escolher escopos da API Google Drive.

fileNotDownloadable

Esse erro ocorre quando você tenta usar o método revisions.get com o parâmetro de URL alt=media em um documento do Google Workspace. O exemplo JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, faça o seguinte:

  • Remova o parâmetro de URL alt=media se quiser conferir os metadados de uma revisão específica, como o mimetype.
  • Use o método files.export para exportar o conteúdo de bytes de um documento do Google Workspace. Para mais informações, consulte Exportar conteúdo de documentos do Google Workspace.

Erros 403

Esses erros significam que um limite de uso foi excedido ou que o usuário não tem os privilégios corretos. Para determinar a causa, avalie o campo reason do JSON retornado.

Para informações sobre os limites da API Drive, consulte Limites de uso. Para saber mais sobre os limites de pastas do Drive, consulte Limites de arquivos e pastas.

activeItemCreationLimitExceeded

Um erro activeItemCreationLimitExceeded ocorre quando o limite do número de itens criados por conta é excedido. Cada usuário pode ter até 500 milhões de itens criados por uma conta. Para mais informações, consulte Limite de itens por usuário.

{
 "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 corrigir esse erro, siga as etapas abaixo:

  1. Informe ao usuário que o Drive impede que as contas criem mais de 500 milhões de itens.

  2. Se o usuário precisar criar itens nessa mesma conta, instrua-o a excluir alguns objetos permanentemente. Caso contrário, eles podem usar uma conta diferente que já atenda ao requisito.

appNotAuthorizedToFile

Esse erro ocorre quando o app não está na ACL do arquivo. Esse erro impede que o usuário abra o arquivo com seu app. O exemplo de JSON abaixo é uma representação desse erro:

{
  "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 corrigir esse erro, tente uma das seguintes opções:

  • Abra o seletor do Google Drive e peça para o usuário abrir o arquivo.
  • Instrua o usuário a abrir o arquivo usando o menu de contexto Open with na interface do Drive do seu app.
  • Use o método files.get para verificar o campo isAppAuthorized no recurso files e conferir se o app criou ou abriu o arquivo.

cannotModifyInheritedTeamDrivePermission

Esse erro ocorre quando um usuário tenta modificar as permissões herdadas de um item em um drive compartilhado. Não é possível remover as permissões herdadas de um item em um drive compartilhado. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, o usuário precisa ajustar as permissões no item pai direto ou indireto de onde elas foram herdadas. Para mais informações, consulte Propagação de permissões. Você também pode extrair o recurso permissions.permissionDetails para saber se as permissões no item do drive compartilhado são herdadas ou aplicadas diretamente.

dailyLimitExceeded

Esse erro ocorre quando o limite da API para o projeto é atingido. O exemplo de JSON abaixo é uma representação desse erro:

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

Esse erro aparece quando o proprietário do app define um limite de cota para limitar o uso de um recurso específico. Para corrigir esse erro, remova todos os limites de uso da cota "Consultas por dia".

domainPolicy

Esse erro ocorre quando a política do domínio do usuário não permite o acesso ao Drive pelo app. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, siga as etapas abaixo:

  1. Informe ao usuário que o domínio não permite que o app acesse arquivos no Drive.
  2. Instrua o usuário a entrar em contato com o administrador do domínio para solicitar acesso ao app.

fileOwnerNotMemberOfTeamDrive

Esse erro ocorre ao tentar mover um arquivo para um drive compartilhado e o proprietário do arquivo não é um participante. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, siga as etapas abaixo:

  1. Adicione o participante ao drive compartilhado com role=owner. Para mais informações, consulte Compartilhar arquivos, pastas e unidades.

  2. Adicione o arquivo ao drive compartilhado. Para mais informações, consulte Criar e preencher pastas.

fileWriterTeamDriveMoveInDisabled

Esse erro ocorre quando um administrador de domínio não permite que usuários com role=writer movam itens para um drive compartilhado. O usuário que está tentando mover os itens tem menos permissões do que o permitido no drive compartilhado de destino. A amostra JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, use a mesma conta de usuário administrador nos drives compartilhados de origem e de destino.

insufficientFilePermissions

Esse erro ocorre quando o usuário não tem acesso de gravação a um arquivo e o app está tentando modificá-lo. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, instrua o usuário a entrar em contato com o proprietário do arquivo e solicitar acesso de edição. Também é possível verificar os níveis de acesso do usuário nos metadados recuperados pelo método files.get e exibir uma interface somente leitura quando as permissões estiverem ausentes.

myDriveHierarchyDepthLimitExceeded

Um erro myDriveHierarchyDepthLimitExceeded ocorre quando o limite do número de níveis de pastas aninhadas é excedido. O Meu Drive de um usuário não pode conter mais de 100 níveis de pastas aninhadas. Para mais informações, consulte Limite de profundidade de pastas.

{
 "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 corrigir esse erro, siga as etapas abaixo:

  1. Informe ao usuário que o Drive impede a colocação de pastas com mais de 100 níveis.
  2. Se o usuário precisar criar outra pasta aninhada, instrua-o a reorganizar a pasta pai desejada para que ela tenha menos de 100 níveis de profundidade ou use uma pasta mãe diferente que já atenda ao requisito.

numChildrenInNonRootLimitExceeded

Esse erro ocorre quando o limite do número de filhos de uma pasta (pastas, arquivos e atalhos) é excedido. Há um limite de 500.000 itens para pastas, arquivos e atalhos diretamente em uma pasta. Itens aninhados em subpastas não são contabilizados nesse limite de 500.000 itens. Para mais informações sobre limites de pastas no Drive, consulte Limites de pastas no Google Drive.

O exemplo de JSON a seguir é uma representação desse erro:

{
 "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 corrigir esse erro, tente uma das seguintes opções:

  • Informe ao usuário que o Drive impede pastas com mais de 500.000 itens.
  • Se o usuário precisar adicionar mais itens à pasta cheia, instrua-o a reorganizar a pasta para que ela contenha menos de 500.000 itens ou use uma pasta semelhante que já tenha menos itens.

rateLimitExceeded

Esse erro ocorre quando o limite de taxa do projeto é atingido. Esse limite varia dependendo do tipo de solicitação. O exemplo de JSON a seguir é uma representação desse erro:

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

Para corrigir esse erro, faça o seguinte:

sharingRateLimitExceeded

Esse erro ocorre quando o usuário atinge um limite de compartilhamento e geralmente está associado a um limite de e-mail. A amostra JSON a seguir é uma representação desse erro:

{
 "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 corrigir esse erro, siga as etapas abaixo:

  1. Não envie e-mails ao compartilhar grandes quantidades de arquivos.
  2. Se um usuário estiver fazendo várias solicitações em nome de muitos usuários de uma conta do Google Workspace, considere uma conta de serviço com delegação em todo o domínio usando o parâmetro quotaUser.

storageQuotaExceeded

Esse erro ocorre quando o usuário atinge o limite de armazenamento. O exemplo de JSON abaixo é uma representação desse erro:

{
 "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 corrigir esse erro, siga as etapas abaixo:

  1. Analise os limites de armazenamento da sua conta do Drive. Para mais informações, consulte Limites de armazenamento e upload do Google Workspace.

  2. Gerenciar arquivos no armazenamento do Google Drive.

  3. Comprar mais armazenamento do Google.

teamDriveFileLimitExceeded

Esse erro ocorre quando um usuário tenta exceder o limite de itens estrito em uma unidade compartilhada. Cada pasta no drive compartilhado de um usuário tem um limite de 500.000 itens, incluindo arquivos, pastas e atalhos. Esse limite é baseado na contagem de itens, não no uso do armazenamento. Para mais informações, consulte Limites do drive compartilhado no Google Drive.

O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, reduza o número de itens no drive compartilhado. Os drives compartilhados com muitos arquivos podem ser difíceis de organizar e pesquisar.

teamDriveHierarchyTooDeep

Um erro teamDriveHierarchyTooDeep ocorre quando o limite do número de níveis de pastas aninhadas do drive compartilhado é excedido. Um drive compartilhado de um usuário não pode conter mais de 100 níveis de pastas aninhadas. Para mais informações, consulte Limite de profundidade de pastas.

{
 "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 corrigir esse erro, siga as etapas abaixo:

  1. Informe ao usuário que os drives compartilhados impedem o posicionamento de pastas com mais de 100 níveis de profundidade.
  2. Se o usuário precisar criar outra pasta aninhada, instrua-o a reorganizar a pasta pai desejada para que ela tenha menos de 100 níveis de profundidade ou use uma pasta mãe diferente que já atenda ao requisito.

teamDriveMembershipRequired

Esse erro ocorre quando um usuário tenta acessar um drive compartilhado do qual não é membro. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, tente uma das seguintes opções:

  1. Peça ao administrador do drive compartilhado para adicionar você com as permissões adequadas para a ação que você precisa realizar.

  2. Analise os papéis e permissões do Drive para saber quem pode acessar e gerenciar drives compartilhados. Outras informações sobre os níveis de acesso também podem ser encontradas em Criar um drive compartilhado.

teamDrivesFolderMoveInNotSupported

Esse erro ocorre quando um usuário tenta mover uma pasta do Meu Drive para um drive compartilhado. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, faça o seguinte:

  • Mova os itens individuais da pasta para um drive compartilhado usando a API Drive. Defina o parâmetro supportsAllDrives=true para indicar o suporte ao Meu Drive e aos drives compartilhados.

  • Se você precisar mover a pasta para um drive compartilhado, use a interface do Drive. Para mais informações, consulte Mover pastas para drives compartilhados como administrador.

teamDrivesParentLimit

Esse erro ocorre quando um usuário tenta adicionar mais de um pai a um item em um drive compartilhado. O exemplo de JSON a seguir é uma representação desse erro:

{
  "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 corrigir esse erro, use os atalhos do Drive para adicionar vários links a um arquivo. Embora um atalho possa ter apenas um pai, um arquivo de atalho pode ser copiado para os outros locais. Para mais informações, consulte Criar um atalho para um arquivo do Drive.

UrlLeaseLimitExceeded

Esse erro ocorre ao tentar salvar dados de jogos do Google Play pelo seu app. O exemplo de JSON a seguir é uma representação desse erro:

{
 "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 corrigir esse erro, conclua ou cancele todos os uploads de um snapshot antes de criar mais.

userRateLimitExceeded

Esse erro ocorre quando o limite por usuário é atingido. Pode ser um limite do console do Google Cloud ou do back-end do Drive. O exemplo de JSON a seguir é uma representação desse erro:

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

Para corrigir esse erro, tente uma das seguintes opções:

Para informações sobre os limites da API Drive, consulte Limites de uso.

Erros 404

Esses erros significam que o recurso solicitado não é acessível ou não existe.

notFound

Esse erro ocorre quando o usuário não tem acesso de leitura a um arquivo ou o arquivo não existe. O exemplo de JSON a seguir é uma representação desse erro:

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

Para corrigir esse erro, siga as etapas abaixo:

  1. Se o arquivo estiver em um drive compartilhado e você estiver usando o método files.get, verifique se o parâmetro de consulta supportsAllDrives está definido como true.
  2. Informe ao usuário que ele não tem acesso de leitura ou que o arquivo não existe.
  3. Instrua o usuário a entrar em contato com o proprietário do arquivo e solicitar permissão para acessar o arquivo.

Erros 429

Esses erros significam que muitas solicitações foram enviadas à API muito rapidamente.

rateLimitExceeded

Esse erro ocorre quando o usuário envia muitas solicitações em um determinado período. O exemplo de JSON a seguir é uma representação desse erro:

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

Para corrigir esse erro, use a espera exponencial para repetir a solicitação.

Erros 500, 502, 503 e 504

Esses erros ocorrem quando um erro inesperado do servidor surge durante o processamento da solicitação. Vários problemas podem causar esses erros, incluindo o tempo de uma solicitação que se sobrepõe a outra ou uma solicitação de uma ação sem suporte, como tentar atualizar as permissões de uma única página no Google Sites em vez de todo o site.

Confira a seguir uma lista de erros 5xx:

  • Erro de back-end 500
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Para corrigir esse erro, use a espera exponencial para repetir a solicitação.