Risolvi gli errori

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

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

Le app Gmail dovrebbero rilevare e gestire tutti gli errori che si possono verificare utilizzando l'API REST. Questa guida fornisce istruzioni su come risolvere errori specifici dell'API.

Risolvere un errore 400: richiesta non valida

Questo errore potrebbe derivare dai seguenti errori del codice:

  • Non è stato specificato un campo o un parametro obbligatorio.
  • Il valore specificato o una combinazione di campi forniti non sono validi.
  • 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 da un'autorizzazione mancante 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 questa operazione non riesce, indirizza l'utente attraverso il flusso OAuth, come descritto in Autorizzazione dell'app con Gmail.

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

Risolvere un errore 403: limite di utilizzo superato

Viene visualizzato un errore 403 quando un limite di utilizzo è stato superato o l'utente non dispone dei 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 utenti è stato superato.
  • Il limite di frequenza del progetto è stato superato.
  • La tua app non può essere utilizzata all'interno del 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 dell'API di cortesia per il 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 questo errore:

  1. Visita la console API di Google
  2. Seleziona il progetto.
  3. Fai clic sulla scheda Quote
  4. Richiedi 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 utenti 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 riprova. Per informazioni sul nuovo tentativo di richieste, consulta Ripetere 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 in base al 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.

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

Un errore domainPolicy si verifica quando il criterio per il dominio dell'utente non consente 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 correggere questo 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 di dominio per richiedere l'accesso per la tua app.

Risolvere l'errore 429: Troppe richieste

Può verificarsi l'errore 429 "Troppe richieste" a causa di limiti giornalieri per utente (inclusi i limiti di invio della posta), limiti di larghezza di banda o di richieste in parallelo per utente. Di seguito sono riportate informazioni su ogni limite. Tuttavia, ogni limite può essere risolto provando a riprovare le richieste non riuscite o suddividendo l'elaborazione tra 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 giornalieri standard della posta. Questi limiti differiscono per gli utenti paganti Google Workspace e per gli utenti di 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 "Limite di frequenza utente superato" "(Invio di posta)" e riprova. 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, potrebbe verificarsi un ritardo di diversi minuti prima che l'API inizi a restituire risposte di errore 429. Non si può quindi dare per scontato che una risposta 200 indichi che l'email è stata inviata correttamente.

Limiti della larghezza di banda

L'API prevede limiti di larghezza di banda per caricamento e download per utente uguali ma indipendenti da IMAP. Questi limiti sono condivisi tra tutti i client dell'API Gmail per un determinato utente.

In genere, questi limiti vengono raggiunti solo in situazioni eccezionali o illecite. Se questi limiti vengono superati, viene restituito un errore HTTP 429 Too Many Requests Viene restituito l'errore "Limite di frequenza utente superato" e viene fornito un tempo per 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 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 di Gmail che accedono a un determinato utente e garantisce che nessun client API sovraccarichi la casella di posta di un utente di Gmail o il suo server di backend.

Questo errore può essere generato dall'invio di molte richieste in parallelo per un singolo utente o dell'invio di batch con un numero elevato di richieste. Questo errore può essere generato anche da un numero elevato di client API indipendenti che accedono contemporaneamente alla casella di posta dell'utente Gmail. Se questo limite viene superato, viene restituito un errore HTTP 429 Too Many Requests Viene restituito l'errore "Troppe richieste in parallelo per l'utente".

Risolvere un errore 500: errore di 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)
  • servizio non disponibile (503)
  • timeout del gateway (504)

Riprova le richieste non riuscite per risolvere gli errori

Puoi riprovare periodicamente una richiesta non riuscita per un periodo di tempo crescente per gestire gli errori relativi a limiti di frequenza, volume di rete o tempi di risposta. Ad esempio, potresti ritentare una richiesta non riuscita dopo un secondo, poi dopo due secondi e poi dopo quattro secondi. Questo metodo è chiamato backoff esponenziale e viene usato per migliorare l'utilizzo della larghezza di banda e massimizzare la velocità effettiva delle richieste in ambienti simultanei.

Avvia un periodo di prova per almeno un secondo dopo l'errore.

Visualizza o modifica i limiti di utilizzo, aumenta 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 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

È consigliabile utilizzare il batch, ma è probabile che dimensioni batch più grandi attivino la limitazione della frequenza. Non è consigliabile inviare batch di oltre 50 richieste. Per informazioni su come raggruppare le richieste, consulta la sezione Richieste di batch.