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 dettagli aggiuntivi che possono aiutarti a determinare come gestire l'errore.

Le app Google Drive dovrebbero rilevare e gestire tutti gli errori che possono verificarsi durante l'utilizzo dell'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 soddisfatta a causa di un errore del client nella richiesta.
401 - Unauthorized La richiesta contiene credenziali non valide.
403 - Forbidden La richiesta è stata ricevuta e comprensibile, ma l'utente non dispone dell'autorizzazione 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 è verificato un errore imprevisto durante l'elaborazione della richiesta.

Errori 400

Questi errori indicano che la richiesta non era accettabile, spesso a causa di un parametro obbligatorio mancante.

badRequest

Questo errore può verificarsi da uno dei seguenti problemi nel codice:

  • Non è stato specificato un campo o un parametro obbligatorio.
  • Il valore specificato o una combinazione di campi forniti non sono validi.
  • Hai provato ad aggiungere un elemento principale duplicato a un file di Drive.
  • Hai provato ad aggiungere un elemento padre che creasse un ciclo nel grafico delle directory.

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 il campo reason del JSON restituito. Questo errore si verifica solitamente perché:

  • La condivisione è riuscita, ma l'email di notifica non è stata recapitata correttamente.
  • La modifica dell'elenco di controllo di 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 (condiviso) che non è riuscito a condividere perché non è stato possibile inviare l'email di notifica all'indirizzo email di destinazione. L'utente deve assicurarsi di avere l'indirizzo email corretto e che possa ricevere 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 le impostazioni di condivisione del dominio Google Workspace a cui appartiene il file. Le impostazioni potrebbero vietare la condivisione all'esterno del dominio o la condivisione di un Drive condiviso potrebbe non essere consentita.

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ò anche essere causato da un'autorizzazione mancante per 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 il token di aggiornamento di lunga durata. Se questa operazione non riesce, indirizza l'utente attraverso il flusso OAuth, come descritto in Scegliere gli ambiti API di Google Drive.

Errori 403

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

Per informazioni sui limiti dell'API Drive, vedi Limiti di utilizzo. Per informazioni sui limiti delle cartelle di Drive, vedi Limiti di file e cartelle.

activeItemCreationLimitExceeded

Un errore activeItemCreationLimitExceeded si verifica quando viene superato il limite del numero di elementi creati per account. Ogni utente può creare fino a 500 milioni di elementi da un account. Per ulteriori informazioni, consulta la sezione Limite di elementi utente.

{
 "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 agli account di creare più di 500 milioni di elementi.

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

appNotAuthorizedToFile

Questo errore si verifica quando l'app non si trova nell'ACL del 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 operazioni:

  • Apri il selettore di Google Drive e chiedi all'utente di aprire il file.
  • Chiedi all'utente di aprire il file utilizzando il menu contestuale Apri con nell'UI di Drive dell'app.
  • Utilizza il metodo files.get per controllare il campo isAppAuthorized nella risorsa files per verificare che la tua app abbia creato o aperto il file.

cannotModifyInheritedTeamDrivePermission

Questo errore si verifica quando un utente tenta di modificare le autorizzazioni ereditate di un elemento all'interno di un Drive condiviso. Non è possibile rimuovere le autorizzazioni ereditate da un elemento di 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 per l'elemento principale diretto o indiretto da cui è stato ereditato. Per maggiori informazioni, consulta Propagazione delle autorizzazioni. Puoi anche recuperare la risorsa permissions.permissionDetails per vedere se le autorizzazioni per questo elemento del Drive condiviso vengono ereditate o applicate direttamente.

dailyLimitExceeded

Questo errore si verifica quando è stato raggiunto il limite API per il progetto. Il seguente 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 per limitare l'utilizzo di una determinata risorsa. Per correggere questo errore, rimuovi eventuali limiti di utilizzo per la quota "Query al giorno".

domainPolicy

Questo errore si verifica quando il criterio per il dominio dell'utente non consente l'accesso a Drive da parte della 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 è un membro. Il seguente esempio JSON è una rappresentazione di questo 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, vedi Condividere file, cartelle e Drive.

  2. Aggiungi il file al Drive condiviso. Per ulteriori informazioni, consulta l'argomento Creare e compilare cartelle.

fileWriterTeamDriveMoveInDisabled

Questo errore si verifica quando un amministratore di dominio non ha consentito agli utenti con role=writer di spostare elementi in un Drive condiviso. L'utente che sta tentando di spostare gli elementi ha meno autorizzazioni di quelle consentite sul Drive condiviso di destinazione. 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 sui Drive condivisi di origine e di destinazione.

insufficientFilePermissions

Questo errore si verifica quando l'utente non ha accesso in scrittura a un file e l'app sta tentando di modificare il file. Il seguente esempio JSON è 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 dal metodo files.get e visualizzare un'interfaccia utente di sola lettura quando mancano le autorizzazioni.

myDriveHierarchyDepthLimitExceeded

Un errore myDriveHierarchyDepthLimitExceeded si verifica quando è stato superato il limite per il numero di livelli di cartelle nidificate. La sezione Il mio Drive di un utente non può contenere più di 100 livelli di cartelle nidificate. Per ulteriori informazioni, consulta Limite di profondità delle cartelle.

{
 "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 inserire cartelle a più di 100 livelli.
  2. Se l'utente deve creare un'altra cartella nidificata, invitalo a riorganizzare la cartella principale prevista in modo che abbia meno di 100 livelli di profondità o a utilizzare una cartella principale diversa che soddisfi già il requisito.

numChildrenInNonRootLimitExceeded

Questo errore si verifica quando viene superato il limite del numero di cartelle secondarie (cartelle, file e scorciatoie) di una cartella. Esiste un limite di 500.000 elementi per cartelle, file e scorciatoie direttamente in una cartella. Gli elementi nidificati in sottocartelle non vengono conteggiati ai fini del limite di 500.000 elementi. Per ulteriori informazioni sui limiti delle cartelle di Drive, vedi Limiti delle cartelle su 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 operazioni:

  • Comunica all'utente che Drive impedisce l'accesso a cartelle con più di 500.000 elementi.
  • Se l'utente deve aggiungere più elementi all'intera cartella, invitalo a riorganizzare la cartella in modo che contenga meno di 500.000 elementi o a utilizzare una cartella simile che contiene già meno elementi.

rateLimitExceeded

Questo errore si verifica quando è stato raggiunto il limite di frequenza del progetto. Il limite varia a seconda del tipo di richiesta. Il seguente esempio JSON è 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 operazioni:

sharingRateLimitExceeded

Questo errore si verifica quando l'utente raggiunge un limite di condivisione ed è spesso collegato a un limite email. Il seguente esempio JSON è una rappresentazione di questo 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 effettua numerose richieste per conto di molti utenti di un account Google Workspace, prendi in considerazione un account di servizio con delega a livello di dominio utilizzando il parametro quotaUser.

storageQuotaExceeded

Questo errore si verifica quando l'utente raggiunge il limite di spazio di archiviazione. Il seguente 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. Rivedi i limiti dello spazio di archiviazione del tuo account Drive. Per saperne di più, consulta Limiti dello spazio di archiviazione e del caricamento di Google Workspace.

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

  3. Acquista altro spazio di archiviazione Google.

teamDriveFileLimitExceeded

Questo errore si verifica quando un utente tenta di superare il limite massimo di elementi consentito su un Drive condiviso. Ogni cartella del Drive condiviso di un utente ha un limite di 400.000 elementi, tra cui file, cartelle e scorciatoie. Questo limite si basa sul numero di elementi, non sull'utilizzo dello spazio di archiviazione. Per maggiori informazioni, consulta Limiti dei Drive condivisi su 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. Nei Drive condivisi con troppi file potrebbe essere difficile organizzare e cercare.

teamDriveMembershipRequired

Questo errore si verifica quando un utente tenta di accedere a un Drive condiviso di cui non è 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 operazioni:

  1. Chiedi al gestore del Drive condiviso di aggiungerti con le autorizzazioni appropriate per l'azione che devi eseguire.

  2. Esamina i ruoli e le autorizzazioni di Drive per sapere chi può accedere e gestire i Drive condivisi. Ulteriori informazioni sui livelli di accesso sono disponibili anche in Creare un Drive condiviso.

teamDrivesFolderMoveInNotSupported

Questo errore si verifica quando un utente tenta di spostare una cartella da Il mio Drive a un Drive condiviso. Il seguente esempio JSON è 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 operazioni:

  • Sposta i singoli elementi dalla cartella a un Drive condiviso utilizzando l'API Drive. Imposta il parametro supportsAllDrives=true per indicare il supporto di Il mio Drive e dei Drive condivisi.

  • Se devi spostare la cartella in un Drive condiviso, utilizza l'interfaccia utente di Drive. Per maggiori informazioni, vedi Spostare cartelle in Drive condivisi come amministratore.

teamDrivesParentLimit

Questo errore si verifica quando un utente tenta di aggiungere più di un elemento principale a un elemento in 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 file. Sebbene una scorciatoia possa avere un solo file principale, è possibile copiare un file nelle posizioni aggiuntive. Per ulteriori informazioni, consulta Creare una scorciatoia a un file di Drive.

UrlLeaseLimitExceeded

Questo errore si verifica quando cerchi di salvare i dati dei giochi di Google Play tramite la tua 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 i caricamenti di uno snapshot prima di crearne altri.

userRateLimitExceeded

Questo errore si verifica quando è stato raggiunto il limite per utente. Potrebbe essere un limite della console Google Cloud o un limite del backend di Drive. 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 operazioni:

Per informazioni sui limiti dell'API Drive, vedi 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 ha accesso in lettura a un file o se il 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 metodo files.get, assicurati che il parametro di query supportsAllDrives sia impostato su true.
  2. Comunica all'utente che non dispone dell'accesso in lettura al file o che il file non esiste.
  3. Chiedi all'utente di contattare il proprietario del file e richiedere l'autorizzazione per accedere al file.

Errori 429

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

rateLimitExceeded

Questo errore si verifica quando l'utente ha inviato troppe richieste in un determinato quantità di tempo. 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 il backoff esponenziale per ritentare la richiesta.

Errori 500, 502, 503, 504

Questi errori si verificano quando si verifica un errore imprevisto del server durante l'elaborazione della richiesta. Questi errori possono causare vari problemi, tra cui la sovrapposizione dei tempi di una richiesta a un'altra richiesta o un'azione non supportata, come il tentativo di aggiornare le autorizzazioni per una singola pagina in Google Sites anziché per l'intero sito.

Di seguito è riportato un elenco di errori 5xx:

  • Errore di backend (500)
  • gateway non valido (502)
  • servizio non disponibile (503)
  • timeout del gateway (504)

Per correggere questo errore, utilizza il backoff esponenziale per ritentare la richiesta.