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 a determinare come gestire l'errore.

Le app Google Drive devono rilevare e gestire tutti gli errori che si possono verificare 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 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 un parametro obbligatorio mancante.

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.

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 file 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. L'utente deve assicurarsi di avere l'indirizzo email corretto e di poter 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 impedire 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ò essere causato anche da una mancanza di autorizzazione 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 quello di lunga durata. Se 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, consulta Limiti di utilizzo. Per informazioni sui limiti per le cartelle di Drive, vedi Limiti di file e cartelle.

activeItemCreationLimitExceeded

Quando viene superato il limite del numero di elementi creati per account, si verifica un errore activeItemCreationLimitExceeded. Ogni utente può creare fino a 500 milioni di elementi creati da un account. Per maggiori informazioni, consulta la sezione Limite degli 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, chiedi di eliminare definitivamente alcuni oggetti. Altrimenti, possono usare un altro account che già soddisfa 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 chiedi all'utente di aprire il file.
  • Chiedi all'utente di aprire il file utilizzando il menu contestuale Apri con nell'interfaccia utente 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. Le autorizzazioni ereditate non possono essere rimosse 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 sono stati ereditati. Per maggiori informazioni, consulta la sezione Propagazione delle autorizzazioni. Puoi anche recuperare la risorsa permissions.permissionDetails per vedere se le autorizzazioni su questo elemento di Drive condiviso sono state ereditate o applicate direttamente.

dailyLimitExceeded

Questo errore si verifica quando è stato raggiunto il limite dell'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 i 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 dalla 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 su Drive.
  2. Chiedi all'utente di contattare l'amministratore di dominio per richiedere l'accesso alla 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, vedi 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 tenta 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 dispone dell'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 una UI 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. Il mio Drive di un utente non può contenere più di 100 livelli di cartelle nidificate. Per maggiori 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 posizionare le cartelle a più di 100 livelli di profondità.
  2. Se l'utente deve creare un'altra cartella nidificata, indica di riorganizzare la cartella principale prevista in modo che abbia una profondità inferiore a 100 livelli o di 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). Esiste un limite di 500.000 elementi per cartelle, file e scorciatoie direttamente in una cartella. Gli elementi nidificati nelle sottocartelle non vengono conteggiati ai fini del limite di 500.000 elementi. Per ulteriori informazioni sui limiti delle cartelle di Drive, consulta l'articolo Limiti per le 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 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 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 viene raggiunto il limite di frequenza del progetto. Questo limite varia in base al 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 soluzioni:

sharingRateLimitExceeded

Questo errore si verifica quando l'utente raggiunge un limite di condivisione ed è spesso collegato a un limite di 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. Esamina i limiti di spazio di archiviazione del tuo account Drive. Per saperne di più, consulta l'articolo Limiti di spazio di archiviazione e caricamento di Google Workspace.

  2. Gestisci 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 rigido di elementi su un 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 elementi, non sull'utilizzo dello spazio di archiviazione. Per maggiori informazioni, vedi 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. I Drive condivisi con troppi file potrebbero essere difficili da organizzare e cercare.

teamDriveHierarchyTooDeep

Un errore teamDriveHierarchyTooDeep si verifica quando è stato superato il limite relativo al numero di livelli di cartelle nidificate nei Drive condivisi. Il Drive condiviso di un utente non può contenere più di 100 livelli di cartelle nidificate. Per maggiori 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 con una profondità superiore a 100 livelli.
  2. Se l'utente deve creare un'altra cartella nidificata, indica di riorganizzare la cartella principale prevista in modo che abbia una profondità inferiore a 100 livelli o di utilizzare una cartella principale diversa che soddisfi già il requisito.

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 soluzioni:

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

  2. Esamina Ruoli e autorizzazioni di Drive per scoprire chi può accedere ai Drive condivisi e gestirli. Puoi trovare ulteriori informazioni sui livelli di accesso 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 soluzioni:

  • 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'UI di Drive. Per ulteriori informazioni, vedi Spostare cartelle su 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. Anche se una scorciatoia può avere un solo elemento principale, un file di scorciatoia può essere copiato in altre posizioni. Per ulteriori informazioni, vedi Creare una scorciatoia a un file di Drive.

UrlLeaseLimitExceeded

Questo errore si verifica quando provi a 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 eventuali 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 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 quando 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 ha 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 il file.

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 periodo 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 riprovare 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 essere causati da vari problemi, tra cui la sovrapposizione dei tempi di una richiesta con un'altra richiesta o una richiesta di un'azione non supportata, come il tentativo di aggiornare le autorizzazioni per una singola pagina in Google Sites anziché l'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 il backoff esponenziale per riprovare la richiesta.