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 detalhes adicionais que podem ajudar a determinar como lidar com o erro.

Os aplicativos do Google Drive detectam e processam 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 bem-sucedida (essa é a resposta padrão para solicitações HTTP bem-sucedidas).
400 - Bad Request A solicitação não pode ser atendida devido a um erro do cliente na solicitação.
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 realizar a solicitação.
404 - Not Found Não foi possível encontrar a página solicitada.
429 - Too Many Requests Há muitas solicitações para a API.
500, 502, 503, 504 - Server Errors Ocorreu um erro inesperado ao processar a solicitação.

Erros 400

Esses erros significam que a solicitação era inaceitável, geralmente devido a um parâmetro obrigatório ausente.

badRequest

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

  • Um campo ou parâmetro obrigatório não foi fornecido.
  • O valor informado 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 do diretório.

O exemplo 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 corretamente.

invalidSharingRequest

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

  • 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, na sigla em inglês) 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 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 pôde ser 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 lista de controle de acesso não é permitida para este usuário

O exemplo 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. Talvez as configurações proíbam o compartilhamento fora do domínio ou o compartilhamento de um drive compartilhado.

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 expira ou é inválido. Esse erro também pode ser causado por falta de autorização para os escopos solicitados. O exemplo 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 para o 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 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. Saiba mais sobre os limites de pastas do Drive em 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 por 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 permanentemente alguns objetos. Caso contrário, ele pode 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 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, tente uma das seguintes opções:

  • 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 IU 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 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. Você também pode recuperar o recurso permissions.permissionDetails para conferir se as permissões nesse item do drive compartilhado são herdadas ou aplicadas diretamente.

dailyLimitExceeded

Esse erro ocorre quando o limite de API do projeto é atingido. O exemplo 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 é exibido quando o proprietário do aplicativo define um limite de cota para o uso de determinado recurso. Para corrigir esse erro, remova todos 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 que seu app acesse o Drive. 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 app.

fileOwnerNotMemberOfTeamDrive

Esse erro ocorre quando você tenta mover um arquivo para um drive compartilhado, sem que o proprietário dele seja participante. 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. Veja mais informações em Compartilhar arquivos, pastas e drives.

  2. Adicione o arquivo ao drive compartilhado. Para saber mais, 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. O exemplo 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 de 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. O exemplo 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 editar. 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

O 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 mãe pretendida para ter menos de 100 níveis ou usar 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 direto em uma pasta. Itens aninhados em subpastas não são contabilizados nesse limite de 500.000 itens. Para mais informações sobre os limites de pastas do Drive, consulte Limites de pastas no Google Drive.

O exemplo 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 completa, instrua-o a reorganizar a pasta para conter menos de 500.000 itens ou usar 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. O exemplo 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, tente uma das seguintes opções:

sharingRateLimitExceeded

Esse erro ocorre quando o usuário atinge um limite de compartilhamento e geralmente está 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 quando estiver compartilhando 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 usar 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 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. Verifique os limites de armazenamento da sua conta do Drive. Para mais informações, consulte Limites de armazenamento e upload do Google Workspace.

  2. Gerencie arquivos no seu armazenamento do Google Drive.

  3. Compre 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 400.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 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. Pode ser difícil organizar e pesquisar drives compartilhados com muitos arquivos.

teamDriveMembershipRequired

Esse erro ocorre quando um usuário tenta acessar um drive compartilhado de que não é membro. O exemplo 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 apropriadas para a ação que precisa ser executada.

  2. Analise as funções e permissões do Drive para saber quem pode acessar e gerenciar drives compartilhados. Mais 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 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, tente uma das seguintes opções:

  • Mova os itens individuais da pasta para um drive compartilhado usando a API Drive. Defina o parâmetro supportsAllDrives=true para indicar o suporte do Meu Drive e dos 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/mãe a um item em um drive compartilhado. O exemplo 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 só possa ter 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 aplicativo. O exemplo 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. Isso pode ser um limite do console do Google Cloud ou do back-end do Drive. O exemplo 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:

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 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. Informe ao usuário que ele não tem acesso de leitura ao arquivo ou que o arquivo não existe.
  2. Instrua o usuário a entrar em contato com o proprietário do arquivo e solicitar permissão para acessá-lo.

Erros 429

Esses erros significam que muitas solicitações foram enviadas à API rápido demais.

rateLimitExceeded

Esse erro ocorre quando o usuário envia solicitações demais em um determinado período. O exemplo 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 fazer a solicitação novamente.

Erros 500, 502, 503 e 504

Esses erros ocorrem quando surge 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 solicitação ou uma solicitação para uma ação não compatível, como tentativa de atualizar permissões para 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 fazer a solicitação novamente.