Risolvi gli errori

L'API Gmail restituisce due livelli di informazioni sugli errori:

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

L'app Gmail deve rilevare e gestire tutti gli errori che potrebbero verificarsi durante l'utilizzo dell'API REST. Questa guida fornisce istruzioni su come risolvere errori specifici dell'API Gmail.

Riepilogo dei codici di stato HTTP

Codice di errore	Descrizione
`200 - OK`	La richiesta è riuscita (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 nella richiesta.
`401 - Unauthorized`	La richiesta contiene credenziali non valide.
`403 - Forbidden`	La richiesta è stata ricevuta e compresa, 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 presenta un errore, spesso dovuto a un parametro obbligatorio mancante.

`badRequest`

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

Non è stato fornito un campo o un parametro obbligatorio.
Il valore fornito o una combinazione di campi forniti non è valido.
L'allegato non è valido.

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.

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 dalla 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 il token di aggiornamento di lunga durata. Se utilizzi una libreria client, la gestione dell'aggiornamento del token viene eseguita automaticamente. Se non va a buon fine, guida l'utente nel flusso OAuth, come descritto in Informazioni sull'autenticazione e l'autorizzazione.

Per ulteriori informazioni sui limiti di Gmail, consulta Limiti di utilizzo.

Errori 403

Questi errori si verificano quando superi un limite di utilizzo o l'utente non dispone dei privilegi corretti. Per determinare la causa, valuta il campo reason del file JSON restituito. Questo errore si verifica nelle seguenti situazioni:

La tua app non può essere utilizzata all'interno del dominio dell'utente autenticato.
Il limite giornaliero è stato superato.
È stato superato il limite di frequenza per utente.
È stato superato il limite di frequenza del progetto.

Per ulteriori informazioni, consulta Limiti di utilizzo.

`dailyLimitExceeded`

Questo errore si verifica quando è stato raggiunto il limite di API per il tuo 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, aumenta la quota nel progetto Google Cloud. Per saperne di più, consulta Gestire i limiti delle quote.

`domainPolicy`

Questo errore si verifica quando le norme per il dominio dell'utente non consentono l'accesso a Gmail da parte della tua app. Il seguente JSON è la rappresentazione di questo errore:

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

Per correggere questo errore, prova a svolgere i seguenti passaggi:

Informa l'utente che il dominio non consente alla tua app di accedere a Gmail.
Chiedi all'utente di contattare l'amministratore di dominio per richiedere l'accesso per la tua app.

`rateLimitExceeded`

Questo errore indica che l'utente ha raggiunto la frequenza massima di richieste dell'API Gmail. Questo 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 a svolgere i seguenti passaggi:

Richiedi un aumento della quota.
Utilizza il backoff esponenziale per riprovare a inviare la richiesta.

`userRateLimitExceeded`

Questo errore si verifica quando è stato raggiunto il limite per utente. 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 risolvere questo errore, prova a ottimizzare il codice dell'applicazione per effettuare meno richieste o utilizza il backoff esponenziale per riprovare a inviare la richiesta.

Errori 429

Un errore 429 "Troppe richieste" può verificarsi a causa dei limiti giornalieri per utente (inclusi i limiti di invio di posta), dei limiti di larghezza di banda o di un limite di richieste simultanee per utente. Di seguito sono riportate informazioni su ciascun limite. Tuttavia, ogni limite può essere risolto riprovando le richieste non riuscite o suddividendo l'elaborazione su più account Gmail.

I limiti per utente non possono essere aumentati per nessun motivo. Per saperne di più sui limiti, consulta Limiti di utilizzo.

Limiti di invio della posta

L'API Gmail applica i limiti standard di invio giornaliero di posta. Questi limiti sono diversi per gli utenti Google Workspace a pagamento e per gli utenti di prova di gmail.com. Per questi limiti, consulta Limiti di invio di Gmail in Google Workspace.

Questi limiti sono per utente e sono condivisi da tutti i client dell'utente, che si tratti di client API, client web o integrati o SMTP MSA. Se questi limiti vengono superati, viene restituito un errore HTTP 429 "Troppe richieste: limite di frequenza per utente superato (invio di posta)" con un tempo di attesa prima di riprovare. Il superamento dei limiti giornalieri potrebbe causare questi errori per diverse ore prima che la richiesta venga accettata.

La pipeline di invio della posta è complessa: una volta che l'utente supera la quota, possono verificarsi ritardi di diversi minuti prima che l'API inizi a restituire risposte di errore 429. Non puoi presumere che una risposta 200 significhi che l'email è stata inviata correttamente.

Limiti di larghezza di banda

L'API ha limiti di larghezza di banda per utente per il caricamento e il download, che sono uguali a quelli di IMAP, ma indipendenti. Questi limiti sono condivisi tra tutti i client dell'API Gmail per un utente.

Questi limiti vengono in genere raggiunti solo in situazioni eccezionali o abusive. Se questi limiti vengono superati, viene restituito un errore HTTP 429 "Troppe richieste: limite di frequenza per utente superato" con un tempo di attesa prima di riprovare. Il superamento dei limiti giornalieri potrebbe causare questi errori per diverse ore prima che la richiesta venga accettata.

Richieste in parallelo

L'API Gmail applica un limite di richieste in parallelo per utente (oltre al limite di frequenza per utente). Questo limite è condiviso da tutti i client API Gmail che accedono a un utente e garantisce che nessun client API sovraccarichi la casella di posta di un utente Gmail o il relativo server di backend.

L'invio di molte richieste parallele per un singolo utente o l'invio di batch con un numero elevato di richieste può attivare questo errore. Anche un numero elevato di client API indipendenti che accedono contemporaneamente alla casella di posta dell'utente Gmail può attivare questo errore. Se questo limite viene superato, viene restituito un errore HTTP 429 "Troppe richieste: Troppe richieste simultanee per l'utente".

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 tempistica di una richiesta che si sovrappone a un'altra richiesta o una richiesta di un'azione non supportata, ad esempio 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:

500 Errore nel backend
502 Bad Gateway
503 - Servizio non disponibile
504 Gateway Timeout

backendError

Questo errore si verifica quando si presenta un errore imprevisto durante l'elaborazione della richiesta. Il seguente esempio JSON è una rappresentazione di questo errore:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

Per risolvere questo errore, utilizza il backoff esponenziale per riprovare a inviare la richiesta.

Rieseguire le richieste non riuscite per risolvere gli errori

Puoi riprovare periodicamente una richiesta non riuscita per un periodo di tempo sempre più lungo per gestire gli errori relativi ai limiti di frequenza, al volume di rete o al tempo di risposta. Ad esempio, potresti riprovare una richiesta non riuscita dopo un secondo, poi dopo due secondi e poi dopo quattro secondi. Questo metodo è chiamato backoff esponenziale e viene utilizzato per migliorare l'utilizzo della larghezza di banda e massimizzare il throughput delle richieste in ambienti simultanei.

Inizia i periodi di nuovi tentativi almeno un secondo dopo l'errore.

Gestisci i limiti di quota

Per visualizzare o modificare i limiti di utilizzo relativi al progetto o per richiedere un incremento della quota, procedi come segue:

Se non hai ancora un account di fatturazione per il progetto, creane uno.
Visita la pagina API abilitate della libreria di API nella console API e seleziona un'API dall'elenco.
Per visualizzare e modificare le impostazioni relative alla quota, seleziona Quote. Per visualizzare le statistiche sull'utilizzo, seleziona Utilizzo.

Per saperne di più, consulta Visualizzare e gestire le quote.

Richieste batch

L'utilizzo di richieste batch è consigliato, tuttavia batch di dimensioni maggiori potrebbero attivare la limitazione della frequenza. L'invio di batch di dimensioni superiori a 50 richieste non è consigliato. Per informazioni su come raggruppare le richieste in batch, consulta la sezione Richieste batch.