Risolvi gli errori

L'API Google Drive restituisce due livelli di informazioni sugli errori:

  • Codici di errore HTTP e messaggi di intestazione.
  • Un oggetto JSON nel corpo della risposta con ulteriori dettagli che possono aiutarti determinare come gestire l'errore.

Le applicazioni Google Drive devono rilevare e gestire tutti gli errori che si possono verificare quando si utilizza l'API REST. Questa guida fornisce istruzioni su come risolvere errori specifici dell'API Drive.

Riepilogo del codice di stato HTTP

Codice di errore Descrizione
200 - OK La richiesta ha esito positivo (questa è la risposta standard per le richieste HTTP riuscite).
400 - Bad Request La richiesta non può essere completata a causa di un errore del client.
401 - Unauthorized La richiesta contiene credenziali non valide.
403 - Forbidden La richiesta è stata ricevuta e compresa, ma l'utente non dispone dell'autorizzazione necessaria per eseguirla.
404 - Not Found Impossibile trovare la pagina richiesta.
429 - Too Many Requests Troppe richieste all'API.
500, 502, 503, 504 - Server Errors Si verifica un errore imprevisto durante l'elaborazione della richiesta.

Errori 400

Questi errori indicano che la richiesta non era accettabile, spesso a causa di una mancanza parametro richiesto.

badRequest

Questo errore può verificarsi a causa di uno dei seguenti problemi nel codice:

  • Non è stato specificato un campo o un parametro obbligatorio.
  • Il valore fornito o una combinazione di campi forniti non è valido.
  • Hai provato ad aggiungere un genitore duplicato a un file di Drive.
  • Hai provato ad aggiungere un elemento padre che avrebbe creato un ciclo nel grafico di directory.
di Gemini Advanced.

Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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."
  }
}

Per correggere questo errore, controlla il campo message e modifica il codice di conseguenza.

invalidSharingRequest

Questo errore si verifica per diversi motivi. Per determinare la causa, valuta Campo reason del JSON restituito. Il più delle volte questo errore si verifica perché:

  • La condivisione è riuscita, ma l'email di notifica non è stata recapitata correttamente.
  • La modifica all'elenco di controllo dell'accesso (ACL) non è consentita per questo utente.

Il campo message indica l'errore effettivo.

Condivisione riuscita, ma l'email di notifica non è stata recapitata correttamente

Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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"
  }
}

Per correggere questo errore, informa l'utente (utente che ha condiviso) che non è stato in grado di effettuare la condivisione perché non è stato possibile inviare l'email di notifica all'indirizzo email di destinazione. La utente deve assicurarsi di avere l'indirizzo email corretto e di poter ricevi email.

La modifica dell'ACL non è consentita per questo utente

Il seguente esempio JSON è una rappresentazione di questo errore:

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

Per correggere questo errore, controlla la condivisione impostazioni del dominio Google Workspace a cui appartiene il file. Le impostazioni potrebbero vietare la condivisione all'esterno del dominio o non condividere consentito.

Errori 401

Questi errori indicano che la richiesta non contiene un token di accesso valido.

authError

Questo errore si verifica quando il token di accesso che stai utilizzando è scaduto o non valido. Questo errore può essere causato anche da una mancanza di autorizzazione per il gli ambiti richiesti. Il seguente esempio JSON è una rappresentazione di questo errore:

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

Per correggere questo errore, aggiorna il token di accesso utilizzando quello di lunga durata. Se non riesce, indirizza l'utente attraverso il flusso OAuth, come descritto in Scegliere Ambiti dell'API Google Drive.

Errori 403

Questi errori indicano che è stato superato un limite di utilizzo o che l'utente non ha i privilegi corretti. Per determinare la causa, valuta il campo reason di il JSON restituito.

Per informazioni sui limiti dell'API Drive, consulta Limiti di utilizzo. Per informazioni sulla cartella Drive limiti, fai riferimento a Limiti di file e cartelle.

activeItemCreationLimitExceeded

Si verifica un errore activeItemCreationLimitExceeded quando il limite per il numero di elementi creati per account è stato superato. Ogni utente può avere fino a 500 milioni di elementi creati da un account. Per ulteriori informazioni, vedi User-item di sicurezza.

{
 "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."
 }
}

Per correggere questo errore:

  1. Comunica all'utente che Drive impedisce la creazione di account più di 500 milioni di elementi.

  2. Se l'utente deve creare elementi nello stesso account, invitalo a eliminare definitivamente alcuni oggetti. Altrimenti, può usare un altro account che soddisfano già il requisito.

appNotAuthorizedToFile

Questo errore si verifica quando l'app non è presente nell'ACL per il file. Questo errore impedisce all'utente di aprire il file con la tua app. Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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}."
  }
}

Per correggere questo errore, prova una delle seguenti soluzioni:

  • Apri il selettore di Google Drive e chiede all'utente di aprire il file.
  • Chiedi all'utente di aprire il file utilizzando il menu contestuale Apri con su Drive UI della tua app.
  • Utilizza il metodo files.get per controlla il campo isAppAuthorized nella files per verificare che creato o aperto dall'app.

cannotModifyInheritedTeamDrivePermission

Questo errore si verifica quando un utente tenta di modificare le autorizzazioni ereditate di un all'interno di un Drive condiviso. Le autorizzazioni ereditate non possono essere rimosse da un elemento in un Drive condiviso. Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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."
  }
}

Per correggere questo errore, un utente deve modificare le autorizzazioni direttamente o indirettamente dall'elemento principale da cui sono stati ereditati. Per ulteriori informazioni, vedi Autorizzazione la propagazione. Puoi recupera anche permissions.permissionDetails risorsa per vedere se le autorizzazioni su questo elemento del Drive condiviso sono ereditate o applicate direttamente.

dailyLimitExceeded

Questo errore si verifica quando è stato raggiunto il limite dell'API per il progetto. Le seguenti L'esempio JSON è una rappresentazione di questo errore:

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

Questo errore viene visualizzato quando il proprietario dell'applicazione ha impostato un limite di quota all'utilizzo di una particolare risorsa. Per correggere questo errore, rimuovi i limiti di utilizzo per nella sezione "Query al giorno" di archiviazione.

domainPolicy

Questo errore si verifica quando il criterio per il dominio dell'utente non consente l'accesso a Guida usando la tua app. Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Drive apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Drive apps."
  }
}

Per correggere questo errore:

  1. Comunica all'utente che il dominio non consente alla tua app di accedere ai file in Drive.
  2. Chiedi all'utente di contattare l'amministratore di dominio per richiedere l'accesso per la tua app.

fileOwnerNotMemberOfTeamDrive

Questo errore si verifica quando tenti di spostare un file in un Drive condiviso e il proprietario del file non ne è membro. Il seguente esempio JSON è una rappresentazione errore:

{
  "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."
  }
}

Per correggere questo errore:

  1. Aggiungi il membro al Drive condiviso con role=owner. Per ulteriori informazioni, consulta l'articolo Condividere file, cartelle e Drive.

  2. Aggiungi il file al Drive condiviso. Per ulteriori informazioni, consulta Creare e gestire completare le cartelle.

fileWriterTeamDriveMoveInDisabled

Questo errore si verifica quando un amministratore di dominio non ha autorizzato gli utenti con role=writer per spostare elementi in un Drive condiviso. L'utente che sta tentando di spostare elemento ha meno autorizzazioni di quelle consentite sul Drive condiviso di destinazione. La il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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."
  }
}

Per correggere questo errore, utilizza lo stesso account utente amministratore su entrambe le origini e i Drive condivisi di destinazione.

insufficientFilePermissions

Questo errore si verifica quando l'utente non dispone dell'accesso in scrittura a un file e sta tentando di modificare il file. Il seguente esempio JSON è un una rappresentazione di questo errore:

{
  "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}."
  }
}

Per correggere questo errore, chiedi all'utente di contattare il proprietario del file e richiedere l'accesso in modifica. Puoi anche controllare i livelli di accesso degli utenti nei metadati recuperati tramite il metodo files.get e viene visualizzata una UI di sola lettura quando mancano autorizzazioni.

myDriveHierarchyDepthLimitExceeded

Si verifica un errore myDriveHierarchyDepthLimitExceeded quando il limite per il valore è stato superato il numero di livelli di cartelle nidificate. L'account di un utente Drive non può contenere più di 100 livelli di cartelle nidificate. Per Per ulteriori informazioni, consulta la sezione Profondità delle cartelle di sicurezza.

{
 "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."
 }
}

Per correggere questo errore:

  1. Comunica all'utente che Drive impedisce di posizionare le cartelle in più di fino a 100 livelli.
  2. Se l'utente deve creare un'altra cartella nidificata, chiedigli di riorganizzarla la cartella principale prevista abbia una profondità inferiore a 100 livelli oppure utilizza un un'altra cartella principale che soddisfa già il requisito.

numChildrenInNonRootLimitExceeded

Questo errore si verifica quando il limite del numero di cartelle secondarie (cartelle, file e scorciatoie) è stato superato. Esiste un limite di 500.000 articoli per cartelle, file e scorciatoie direttamente in una cartella. Elementi nidificati in sottocartelle non vengono conteggiate ai fini del limite di 500.000 elementi. Per ulteriori informazioni Limiti delle cartelle di Drive. Fai riferimento a Limiti per le cartelle in Google Drive.

Il seguente esempio JSON è una rappresentazione di questo errore:

{
 "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."
 }
}

Per correggere questo errore, prova una delle seguenti soluzioni:

  • Comunica all'utente che Drive impedisce le cartelle con più di 500.000 elementi.
  • Se l'utente deve aggiungere altri elementi all'intera cartella, invitalo a riorganizza la cartella in modo che contenga meno di 500.000 elementi o utilizza un cartella che contiene già meno elementi.

rateLimitExceeded

Questo errore si verifica quando viene raggiunto il limite di frequenza del progetto. Questo limite varia in base al tipo di richiesta. Il seguente esempio JSON è un una rappresentazione di questo errore:

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

Per correggere questo errore, prova una delle seguenti soluzioni:

sharingRateLimitExceeded

Questo errore si verifica quando l'utente raggiunge un limite di condivisione ed è spesso collegato con un limite di email. Il seguente esempio JSON è una rappresentazione errore:

{
 "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"
 }
}

Per correggere questo errore:

  1. Non inviare email quando condividi grandi quantità di file.
  2. Se un utente invia numerose richieste per conto di molti utenti di un Account Google Workspace, prendi in considerazione un account di servizio a livello di dominio delega utilizzando lo strumento quotaUser parametro.

storageQuotaExceeded

Questo errore si verifica quando l'utente raggiunge il limite di spazio di archiviazione. Le seguenti L'esempio JSON è una rappresentazione di questo errore:

{
 "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."
 }
}

Per correggere questo errore:

  1. Esamina i limiti di spazio di archiviazione del tuo account Drive. Per ulteriori informazioni informazioni, consulta l'articolo Spazio di archiviazione e caricamento di Google Workspace limiti.

  2. Gestire i file su Google Drive spazio di archiviazione.

  3. Acquista altri prodotti Google spazio di archiviazione.

teamDriveFileLimitExceeded

Questo errore si verifica quando un utente cerca di superare il limite massimo di elementi su una Drive condiviso. Ogni cartella del Drive condiviso di un utente ha un limite di 500.000 elementi. inclusi file, cartelle e scorciatoie. Questo limite si basa sul numero di articoli, non l'utilizzo dello spazio di archiviazione. Per saperne di più, vedi Limiti dei Drive condivisi in Google Drive.

Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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."
  }
}

Per correggere questo errore, riduci il numero di elementi nel Drive condiviso. Drive condivisi con troppi file potrebbe essere difficile organizzare e cercare.

teamDriveHierarchyTooDeep

Un errore teamDriveHierarchyTooDeep si verifica quando il limite di numero i livelli delle cartelle nidificate dei Drive condivisi sono stati superati. Il Drive condiviso di un utente non può contengono più di 100 livelli di cartelle nidificate. Per ulteriori informazioni, vedi Limite di profondità delle cartelle.

{
 "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."
 }
}

Per correggere questo errore:

  1. Comunica all'utente che i Drive condivisi impediscono di posizionare le cartelle in posizioni superiori a fino a 100 livelli.
  2. Se l'utente deve creare un'altra cartella nidificata, chiedigli di riorganizzarla la cartella principale prevista abbia una profondità inferiore a 100 livelli oppure utilizza un un'altra cartella principale che soddisfa già il requisito.

teamDriveMembershipRequired

Questo errore si verifica quando un utente tenta di accedere a un Drive condiviso in cui si trova non è un membro. Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveMembershipRequired",
        "message": "The attempted action requires shared drive membership."
      }
    ],
    "code": 403,
    "message": "The attempted action requires shared drive membership."
  }
}

Per correggere questo errore, prova una delle seguenti soluzioni:

  1. Chiedi al gestore del Drive condiviso di aggiungerti con l'appropriata le autorizzazioni per l'azione da eseguire.

  2. Esamina i ruoli e i ruoli di Drive autorizzazioni per sapere chi può accedere e gestire Drive condivisi. Sono inoltre disponibili ulteriori informazioni sui livelli di accesso alla pagina Crea un file condiviso in auto.

teamDrivesFolderMoveInNotSupported

Questo errore si verifica quando un utente tenta di spostare una cartella da Personale su un Drive condiviso. Il seguente esempio JSON è un una rappresentazione di questo errore:

{
  "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."
  }
}

Per correggere questo errore, prova una delle seguenti soluzioni:

  • Sposta i singoli elementi dalla cartella a un Drive condiviso utilizzando API Drive. Imposta il parametro supportsAllDrives=true per indicare la sia per Il mio Drive sia per i Drive condivisi.

  • Se devi spostare la cartella su un Drive condiviso, utilizza la UI di Drive. Per ulteriori informazioni, vedi Spostare le cartelle in file condivisi come amministratore.

teamDrivesParentLimit

Questo errore si verifica quando un utente tenta di aggiungere più di un elemento principale a un elemento in su un Drive condiviso. Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "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."
  }
}

Per correggere questo errore, utilizza le scorciatoie di Drive per aggiungere più link a un . Anche se una scorciatoia può avere un solo file principale, un file di scorciatoia può essere copiato in altre posizioni. Per ulteriori informazioni, consulta la sezione Creare un scorciatoia a un file di Drive.

UrlLeaseLimitExceeded

Questo errore si verifica quando provi a salvare i dati dei giochi di Google Play tramite il tuo un'applicazione. Il seguente esempio JSON è una rappresentazione di questo errore:

{
 "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."
 }
}

Per correggere questo errore, completa o annulla tutti i caricamenti di un'istantanea prima di crearla altro ancora.

userRateLimitExceeded

Questo errore si verifica quando è stato raggiunto il limite per utente. Potrebbe trattarsi di un un limite dalla console Google Cloud o un limite dalla versione di Drive di un backend cloud. Il seguente esempio JSON è una rappresentazione di questo errore:

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

Per correggere questo errore, prova una delle seguenti soluzioni:

Per informazioni sui limiti dell'API Drive, consulta Limiti di utilizzo.

Errori 404

Questi errori indicano che la risorsa richiesta non è accessibile o non esiste.

notFound

Questo errore si verifica quando l'utente non dispone dell'accesso in lettura a un file o al file non esiste. Il seguente esempio JSON è una rappresentazione di questo errore:

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

Per correggere questo errore:

  1. Se il file si trova su un Drive condiviso e utilizzi il files.get, assicurati che il valore Il parametro di query supportsAllDrives è impostato su true.
  2. Comunica all'utente che non ha accesso in lettura al file o al file non esiste.
  3. Chiedi all'utente di contattare il proprietario del file e richiedere l'autorizzazione al .

Errori 429

Questi errori indicano che sono state inviate troppe richieste all'API troppo rapidamente.

rateLimitExceeded

Questo errore si verifica quando l'utente ha inviato troppe richieste in un determinato per un periodo di tempo limitato. Il seguente esempio JSON è una rappresentazione di questo errore:

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

Per correggere questo errore, utilizza l'impostazione Esponenziale backoff per eseguire nuovamente la richiesta.

Errori 500, 502, 503, 504

Questi errori si verificano quando si verifica un errore imprevisto del server durante l'elaborazione richiesta. Questi errori possono essere causati da vari problemi, tra cui la tempistica di una richiesta sovrapporsi a un'altra richiesta o a una richiesta di azione non supportata, ad esempio tentare di aggiornare le autorizzazioni per una singola pagina in Google Sites anziché all'intero sito.

Di seguito è riportato un elenco degli errori 5xx:

  • Errore 500 di backend
  • 502 - Gateway non valido
  • 503 Servizio non disponibile
  • 504 Timeout del gateway

Per correggere questo errore, utilizza l'impostazione Esponenziale backoff per eseguire nuovamente la richiesta.