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

Le app Gmail devono 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.

Risolvere un errore 400: richiesta non valida

Questo errore potrebbe essere causato da questi errori nel codice:

  • Non è stato fornito un campo o un parametro obbligatorio.
  • Il valore fornito o una combinazione di campi forniti non è valido.
  • Allegato non valido.

Di seguito è riportata una rappresentazione JSON di esempio 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.

Risolvere un errore 401: credenziali non valide

Un errore 401 indica che il token di accesso che stai utilizzando è scaduto o non è valido. Questo errore può essere causato anche dall'assenza dell'autorizzazione per gli scopi richiesti. Di seguito è riportata la rappresentazione JSON 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 a lungo termine. Se utilizzi una libreria client, questa gestisce automaticamente il rinnovo del token. Se l'operazione non va a buon fine, invita l'utente a seguire il flusso OAuth, come descritto in Autorizzare l'app con Gmail.

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

Risolvere un errore 403: limite di utilizzo superato

Si verifica un errore 403 quando viene superato un limite di utilizzo o l'utente non possiede i privilegi corretti. Per determinare il tipo specifico di errore, valuta il campo reason del JSON restituito. Questo errore si verifica nelle seguenti situazioni:

  • Il limite giornaliero è stato superato.
  • Il limite di frequenza degli utenti è stato superato.
  • È stato superato il limite di frequenza del progetto.
  • La tua app non può essere utilizzata nel dominio dell'utente autenticato.

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

Risolvere un errore 403: limite giornaliero superato

Un errore dailyLimitExceeded indica che è stato raggiunto il limite di API di cortesia per il tuo progetto. Di seguito è riportata la rappresentazione JSON di questo errore:

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

Per correggere l'errore:

  1. Visita la console API di Google
  2. Seleziona il progetto.
  3. Fai clic sulla scheda Quote.
  4. Richiedi una quota aggiuntiva. Per ulteriori informazioni, consulta Richiedere una quota aggiuntiva.

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

Risolvere un errore 403: limite di frequenza per utente superato

Un errore userRateLimitExceeded indica che è stato raggiunto il limite per utente. Di seguito è riportata la representation JSON 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 a ottimizzare il codice dell'applicazione in modo da effettuare meno richieste o riprovare. Per informazioni su come ripetere le richieste, consulta Rieseguire le richieste non riuscite per risolvere gli errori.

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

Risolvere un errore 403: limite di frequenza superato

Un errore rateLimitExceeded indica che l'utente ha raggiunto la frequenza massima di richieste dell'API Gmail. Questo limite varia a seconda del tipo di richieste. Di seguito è riportata la rappresentazione JSON di questo errore:

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

Per correggere questo errore, riprova le richieste non riuscite.

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

Risolvere un errore 403: l'app con ID {appId} non può essere utilizzata nel dominio dell'utente autenticato

Si verifica un errore domainPolicy quando i criteri per il dominio dell'utente non consentono all'app di accedere a Gmail. Di seguito è riportata la rappresentazione JSON 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 l'errore:

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

Risolvere un errore 429: troppe richieste

Un errore 429 "Troppe richieste" può verificarsi a causa di limiti giornalieri per utente (inclusi i limiti di invio di email), limiti di larghezza di banda o un limite di richieste contemporaneamente per utente. Di seguito sono riportate le informazioni su ciascun limite. Tuttavia, ogni limite può essere risolto tentando di riprovare le richieste non riuscite o suddividendo l'elaborazione su più account Gmail. I limiti per utente non possono essere aumentati per nessun motivo. Per ulteriori informazioni sui limiti, consulta Limiti di utilizzo.

Limiti di invio della posta

L'API Gmail applica i limiti di invio giornaliero della posta standard. Questi limiti differiscono per gli utenti Google Workspace paganti e per gli utenti con prova 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 nativi/web o MSA SMTP. Se questi limiti vengono superati, viene restituito un errore HTTP 429 Too Many Requests "Superato il limite di frequenza degli utenti" "(invio di email)" con il tempo per riprovare. Tieni presente che il superamento dei limiti giornalieri può comportare questi tipi di errori per diverse ore prima dell'accettazione della richiesta.

La pipeline di invio della posta è complessa: una volta che l'utente ha superato la quota, puoi verificarsi un ritardo di diversi minuti prima che l'API inizi a restituire risposte di errore 429. Pertanto, non puoi presumere che una risposta 200 indichi che l'email è stata inviata correttamente.

Limiti di larghezza di banda

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

Questi limiti vengono in genere raggiunti solo in situazioni eccezionali o illecite. Se questi limiti vengono superati, viene restituito un errore HTTP 429 Too Many Requests "Limite di frequenza utenti superato" con un tempo per riprovare. Tieni presente che il superamento dei limiti giornalieri può comportare questi tipi di errori per diverse ore prima che la richiesta venga accettata.

Richieste in parallelo

L'API Gmail applica un limite di richieste concorrenti per utente (oltre al limite di frequenza per utente). Questo limite è condiviso da tutti i client API Gmail che accedono a un determinato 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 in parallelo per un singolo utente o l'invio di batch con un gran numero 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 Too Many Requests "Troppe richieste in parallelo per utente".

Risolvere un errore 500: errore nel backend

Un backendError si verifica quando si verifica un errore imprevisto durante l'elaborazione della richiesta.

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

Per correggere questo errore, riprova le richieste non riuscite. Di seguito è riportato un elenco di errori 500:

  • Gateway non valido (502)
  • 503 Servizio non disponibile
  • Timeout del gateway (504)

Riprovare le richieste non riuscite per risolvere gli errori

Puoi riprovare periodicamente una richiesta non riuscita per un periodo di tempo sempre maggiore per gestire gli errori relativi a limiti di frequenza, volume della rete o tempo di risposta. Ad esempio, puoi riprovare a inviare una richiesta non riuscita dopo un secondo, poi dopo due secondi e infine dopo quattro secondi. Questo metodo si chiama backoff esponenziale e viene utilizzato per migliorare l'utilizzo della larghezza di banda e massimizzare la velocità in uscita delle richieste in ambienti contemporaneamente.

Avvia i periodi di ripetizione almeno un secondo dopo l'errore.

Visualizzare o modificare i limiti di utilizzo, aumentare la quota

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

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

Richieste batch

L'utilizzo del batching è consigliato, tuttavia è probabile che i batch di dimensioni maggiori attiveranno il limite di frequenza. Non è consigliabile inviare batch di dimensioni superiori a 50 richieste. Per informazioni su come raggruppare le richieste, consulta la sezione Creare batch di richieste.