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 você a determinar como lidar com o erro.

Os aplicativos do Google Drive precisam capturar e processar todos os erros que podem ser encontrados durante o uso da 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 é bem-sucedida (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 entendida, 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 Excesso de solicitações para a API.
500, 502, 503, 504 - Server Errors Ocorreu um erro inesperado durante o processamento da solicitação.

Erros 400

Esses erros significam que a solicitação era inaceitável, muitas vezes devido à ausência de um parâmetro obrigatório.

badRequest

Esse erro pode ocorrer devido a um dos seguintes problemas no seu código:

  • Um campo ou parâmetro obrigatório não foi fornecido.
  • O valor fornecido ou uma combinação dos 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 seu 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 ocorre com mais frequência porque:

  • O compartilhamento foi concluído, mas o e-mail de notificação não foi entregue corretamente.
  • A alteração da Lista de controle de acesso (ACL) não é permitida para este usuário.

O campo message indica o erro real.

O compartilhamento foi concluído, 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 verificar se tem o endereço de e-mail correto e se pode receber e-mails.

A alteração da 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 a que 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 expirou 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 do OAuth, conforme descrito em Escolher escopos da API Google Drive.

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.

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

activeItemCreationLimitExceeded

Um erro activeItemCreationLimitExceeded ocorre quando o limite para o número de itens criados por conta é excedido. Cada usuário pode ter até 500 milhões de itens criados em uma conta. Para mais informações, consulte Limite de itens do 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, é possível 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 o app. O exemplo JSON a seguir é 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, faça o seguinte:

  • Abra o seletor do Google Drive e solicite que o usuário abra o arquivo.
  • Instrua o usuário a abrir o arquivo usando o menu de contexto Abrir com 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, um usuário precisa ajustar as permissões no item pai direto ou indireto de que elas foram herdadas. Para mais informações, consulte Propagação de permissões. Também é possível recuperar o recurso permissions.permissionDetails para ver se as permissões nesse item do drive compartilhado são herdadas ou aplicadas diretamente.

dailyLimitExceeded

Esse erro ocorre quando o limite da API para o projeto é atingido. A amostra de JSON a seguir é 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 aplicativo define um limite de cota para limitar o uso de um recurso específico. Para corrigir esse erro, remova os limites de uso da cota de "Consultas por dia".

domainPolicy

Esse erro ocorre quando a política do domínio do usuário não permite acesso ao Drive pelo app. O exemplo 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 aplicativo.

fileOwnerNotMemberOfTeamDrive

Esse erro ocorre ao tentar mover um arquivo para um drive compartilhado e o proprietário não é um membro. A amostra 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 os 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 seu app está tentando modificar o arquivo. A amostra 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 para edição. Também é possível verificar os níveis de acesso do usuário nos metadados recuperados pelo método files.get e mostrar uma interface somente leitura quando as permissões estiverem ausentes.

myDriveHierarchyDepthLimitExceeded

Um erro myDriveHierarchyDepthLimitExceeded ocorre quando o limite para o 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 o armazenamento 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 pretendida para que tenha menos de 100 níveis de profundidade ou use uma pasta pai diferente que já atenda ao requisito.

numChildrenInNonRootLimitExceeded

Esse erro ocorre quando o limite para o 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. Os itens aninhados em subpastas não são contabilizados nesse limite de 500 mil itens. Para mais informações sobre os limites de pastas do 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, faça o seguinte:

  • Informe ao usuário que o Drive impede pastas com mais de 500.000 itens.
  • Se o usuário precisar adicionar mais itens à pasta completa, instrua-o a reorganizá-la para que contenha menos de 500 mil itens ou use uma pasta semelhante que já contenha menos itens.

rateLimitExceeded

Esse erro ocorre quando o limite de taxa do projeto é atingido. Esse limite varia de acordo com o tipo de solicitação. A amostra 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 é vinculado 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. A amostra de JSON a seguir é 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 do armazenamento no Google Drive.

  3. Comprar mais armazenamento do Google.

teamDriveFileLimitExceeded

Esse erro ocorre quando um usuário tenta exceder o limite de itens em um drive compartilhado. 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. Drives compartilhados com muitos arquivos podem ser difíceis de organizar e pesquisar.

teamDriveHierarchyTooDeep

Um erro teamDriveHierarchyTooDeep ocorre quando o limite para o número de níveis de pastas aninhadas no drive compartilhado é excedido. O 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 pretendida para que tenha menos de 100 níveis de profundidade ou use uma pasta pai diferente que já atenda ao requisito.

teamDriveMembershipRequired

Esse erro ocorre quando um usuário tenta acessar um drive compartilhado de que ele 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, faça o seguinte:

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

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

teamDrivesFolderMoveInNotSupported

Esse erro ocorre quando um usuário tenta mover uma pasta do Meu Drive para um drive compartilhado. A amostra 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. Veja mais informações em 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 saber mais, consulte Criar um atalho para um arquivo do Drive.

UrlLeaseLimitExceeded

Esse erro ocorre ao tentar salvar dados de jogos do Google Play usando 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, faça o seguinte:

Saiba mais sobre os limites da API Drive em Limites de uso.

Erros 404

Esses erros significam que o recurso solicitado não está 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 localizado 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 ele.

Erros 429

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

rateLimitExceeded

Esse erro ocorre quando o usuário envia solicitações demais 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, 504

Esses erros ocorrem quando ocorre um erro inesperado do servidor durante o processamento da solicitação. Vários problemas podem causar esses erros, incluindo a sobreposição do tempo de uma solicitação com outra ou a solicitação de uma ação não compatível. Por exemplo, a tentativa de atualizar permissões de uma única página no Google Sites em vez de todo o site.

Confira a seguir uma lista de erros 5xx:

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

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