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.

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 API specifici.

Risolvere un errore 400: richiesta errata

Questo errore potrebbe essere dovuto ai seguenti errori nel tuo 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ò anche essere causato dalla mancanza di autorizzazione per gli ambiti 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 di lunga durata. Se utilizzi una libreria client, questa gestisce automaticamente l'aggiornamento dei token. Se l'operazione non va a buon fine, guida l'utente nel flusso OAuth, come descritto in Autorizzare l'app con Gmail.

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

Risolvere un errore 403: limite di utilizzo superato

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

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

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

Risolvere l'errore 403: limite giornaliero superato

Un errore dailyLimitExceeded indica che è stato raggiunto il limite 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 risolvere l'errore:

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

Per ulteriori informazioni sui limiti di Gmail, consulta la sezione 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 rappresentazione 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 per effettuare meno richieste o riprovare. Per informazioni sui tentativi ripetuti, consulta Rieseguire le richieste non riuscite per risolvere gli errori.

Per ulteriori informazioni sui limiti di Gmail, consulta la sezione 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 l'errore, riprova a inviare le richieste non riuscite.

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

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

Si verifica un errore domainPolicy quando le norme per il dominio dell'utente non consentono l'accesso a Gmail da parte della tua app. 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 risolvere l'errore:

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

Risolvere un errore 429: troppe richieste

L'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 provando a ripetere le richieste non riuscite o dividendo l'elaborazione su più account Gmail. I limiti per utente non possono essere aumentati per nessun motivo. Per ulteriori informazioni sui limiti, vedi Limiti di utilizzo.

Limiti di invio della posta

L'API Gmail applica i limiti standard di invio giornaliero di posta. Questi limiti variano per gli utenti paganti e per gli utenti di prova di gmail.com. Per questi limiti, consulta Limiti di invio di Gmail in .

Questi limiti sono per utente e sono condivisi da tutti i client dell'utente, che si tratti di client API, client nativi/web o SMTP MSA. Se questi limiti vengono superati, viene restituito un errore HTTP 429 Too Many Requests "User-rate limit exceeded" (Superato il limite di frequenza per utente) "(Invio di posta)" con il tempo di riprovare. Tieni presente che il superamento dei limiti giornalieri può causare questi tipi di 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 essere necessari diversi minuti prima che l'API inizi a restituire risposte di errore 429. Pertanto, 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 caricamenti e download per utente 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 abusive. Se questi limiti vengono superati, viene restituito un errore HTTP 429 Too Many Requests "User-rate limit exceeded" (Superato il limite di frequenza per utente) con un tempo di attesa prima di riprovare. Tieni presente che il superamento dei limiti giornalieri può causare questi tipi di errori per diverse ore prima che la richiesta venga accettata.

Richieste simultanee

L'API Gmail applica un limite di richieste simultanee per utente (oltre al limite di frequenza per utente). Questo limite è condiviso da tutti i client dell'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 parallele per un singolo utente o l'invio di batch con un numero elevato di richieste può attivare questo errore. Un numero elevato di client API indipendenti che accedono contemporaneamente alla casella di posta dell'utente Gmail può anche attivare questo errore. Se questo limite viene superato, viene restituito un errore HTTP 429 Too Many Requests "Too many concurrent requests for user" (Troppe richieste simultanee per l'utente).

Risolvere un errore 500: errore nel backend

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

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

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

  • 502 Bad Gateway
  • 503 - Servizio non disponibile
  • 504 Timeout gateway

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.

Avvia i periodi di nuovi tentativi 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 batch di dimensioni maggiori potrebbero attivare la limitazione della frequenza. Non è consigliabile inviare batch con più di 50 richieste. Per informazioni su come raggruppare le richieste in batch, consulta la sezione Richieste batch.