corrigir erros.

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

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

Os apps do 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.

Resolver um erro 400: solicitação inválida

Esse erro pode ser causado 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 familiar responsável duplicado a um arquivo do Drive.
  • Você tentou adicionar um pai que criaria um ciclo no gráfico do diretório.

Veja a seguir um exemplo de representação JSON 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.

Resolver um erro 400: solicitação de compartilhamento inválida

Esse erro pode ocorrer por vários motivos. Para determinar o limite que foi excedido, 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 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

Veja a representação JSON 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 com que ele quer compartilhar. 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

Veja a representação JSON 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 Google Workspace ao qual o arquivo pertence. As configurações podem proibir o compartilhamento fora do domínio ou não permitir o compartilhamento de um drive compartilhado.

Resolver um erro 401: credenciais inválidas

Um erro 401 indica que o token de acesso usado está expirado ou inválido. Esse erro também pode ser causado pela falta de autorização para os escopos solicitados. Veja a representação JSON 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 falhar, direcione o usuário pelo fluxo do OAuth, conforme descrito em Informações de autorização e autenticação específicas da API.

Resolver um erro 403

Um erro 403 ocorre quando um limite de uso é excedido ou o usuário não tem os privilégios corretos. Para determinar o tipo específico de erro, avalie o campo reason do JSON retornado. Esse erro ocorre nas seguintes situações:

  • O limite diário foi excedido.
  • O limite de taxa de usuário foi excedido.
  • O limite de taxa do projeto foi excedido.
  • O limite da taxa de compartilhamento foi excedido.
  • O usuário não concedeu os direitos do app a um arquivo.
  • O usuário não tem permissões suficientes para um arquivo.
  • Não é possível usar o app no domínio do usuário conectado.
  • O número de itens em uma pasta foi excedido.

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

Resolver um erro 403: o limite diário foi excedido

Um erro dailyLimitExceeded indica que o limite da API de cortesia para seu projeto foi atingido. Veja a representação JSON 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 "Consultas por dia".

Resolver um erro 403: o limite da taxa de usuário foi excedido

Um erro userRateLimitExceeded indica que o limite por usuário foi atingido. Pode ser um limite no Console de APIs do Google ou no back-end do Drive. Veja a representação JSON desse erro:

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

Para corrigir esse erro, siga uma destas opções:

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

Resolver um erro 403: o limite de taxa do projeto foi excedido

Um erro rateLimitExceeded indica que o limite de taxa do projeto foi atingido. Esse limite varia de acordo com o tipo de solicitação. Veja a representação JSON desse erro:

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

Para corrigir esse erro, siga uma destas opções:

Resolver um erro 403: o limite de taxa de compartilhamento foi excedido

Um erro sharingRateLimitExceeded ocorre quando o usuário atinge um limite de compartilhamento. Esse erro geralmente está vinculado a um limite de e-mail. Veja a representação JSON 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 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.

Resolver um erro 403: cota de armazenamento excedida

Um erro storageQuotaExceeded ocorre quando o usuário atinge o limite de armazenamento. Veja a representação JSON 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 upload e armazenamento no Drive.

  2. Liberar espaço

    ou tenha mais armazenamento com o Google One.

Resolver um erro 403: o usuário não concedeu ao app {appId} {verb} acesso ao arquivo {fileId}

Um erro appNotAuthorizedToFile ocorre quando o app não está na ACL do arquivo. Esse erro impede que o usuário abra o arquivo com o app. Veja a seguir a representação JSON do 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, siga uma destas opções:

Também é possível verificar o campo isAppAuthorized em um arquivo para conferir se o app criou ou abriu o arquivo.

Resolver um erro 403: o usuário não tem permissões suficientes para o arquivo {fileId}

Um erro insufficientFilePermissions ocorre quando o usuário não tem acesso de gravação a um arquivo e o app está tentando modificar o arquivo. Veja a seguir a representação JSON 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 por files.get e exibir uma IU somente leitura quando as permissões estiverem ausentes.

Resolver um erro 403: o app com o ID {appId} não pode ser usado no domínio do usuário autenticado

Um erro domainPolicy ocorre quando a política para o domínio do usuário não permite acesso ao Drive pelo app. Veja a representação JSON 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 para o app.

Resolver um erro 403: o número de itens na pasta foi excedido

Um erro numChildrenInNonRootLimitExceeded 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.

Resolver um erro 403: o número de itens criados pela conta foi excedido

Um erro activeItemCreationLimitExceeded ocorre quando o limite para o número de itens, descartados ou não, criado por essa conta é excedido. Todos os tipos de item, incluindo pastas, são contabilizados no limite.

Resolva um erro 404: arquivo não encontrado: {fileId}

O erro notFound ocorre quando o usuário não tem acesso de leitura a um arquivo ou o arquivo não existe.

{
  "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 para ler 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 o arquivo.

Resolver um erro 429: muitas solicitações

Um erro rateLimitExceeded ocorre quando o usuário envia muitas solicitações em um determinado período.

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

Para corrigir esse erro, use a espera exponencial (link em inglês) para repetir a solicitação.

Resolver um erro 5xx

Ocorre um erro 5xx quando ocorre um erro inesperado ao processar a solicitação. Isso pode ser causado por vários problemas, incluindo a marcação de tempo de uma solicitação sobreposta a outra ou uma solicitação de uma ação não compatível, como a tentativa de atualizar permissões de uma única página em um site Google em vez do próprio site.

Para corrigir esse erro, use a espera exponencial (link em inglês) para repetir a solicitação. Veja a seguir uma lista de erros 5xx:

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