Risolvere 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 dovrebbe rilevare e gestire tutti gli errori che si verificano quando utilizzi l'API REST. Questa guida fornisce istruzioni su come risolvere errori specifici dell'API Gmail.

Riepilogo del codice di stato HTTP

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:

• Manca un campo o un parametro obbligatorio.
• Un valore fornito o una combinazione di campi 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. Anche l'autorizzazione mancante per gli ambiti richiesti può causare questo errore. 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 dei 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 progetto ha superato il limite giornaliero.
• L'utente ha superato il limite di frequenza.
• Il progetto ha superato il limite di frequenza.

Per ulteriori informazioni, consulta Limiti di utilizzo.

dailyLimitExceeded

Questo errore si verifica quando il progetto raggiunge il limite API. 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 si verifica quando il proprietario dell'applicazione imposta 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 il criterio per il dominio dell'utente non consente alla tua app di accedere a Gmail. 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:

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.

rateLimitExceeded

Questo errore indica che l'utente ha raggiunto la frequenza massima di richieste per l'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 una richiesta raggiunge 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 di limiti giornalieri per utente (inclusi i limiti di invio di posta), limiti di larghezza di banda o 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.

Non puoi aumentare i limiti per utente. Per ulteriori informazioni 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 superi questi limiti, l'API restituisce un errore HTTP 429 "Troppe richieste: superato il limite di frequenza per utente (invio di email)" con un tempo di attesa per il nuovo tentativo. Il superamento dei limiti giornalieri potrebbe causare questi errori per diverse ore prima che il server accetti la richiesta.

La pipeline di invio della posta è complessa: una volta che l'utente supera la quota, possono trascorrere 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 pari a quelli di IMAP, ma indipendenti da questi. Questi limiti sono condivisi tra tutti i client dell'API Gmail per un utente.

In genere, gli utenti incontrano questi limiti solo in situazioni eccezionali o abusive. Se superi questi limiti, l'API restituisce un errore HTTP 429 "Troppe richieste: superato il limite di frequenza per utente" con un tempo di attesa prima di riprovare. Il superamento dei limiti giornalieri potrebbe causare questi errori per diverse ore prima che il server accetti la richiesta.

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 superi questo limite, l'API restituisce un errore HTTP 429 "Too many requests: Too many concurrent requests for user" (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
• Servizio non disponibile (503)
• 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 la velocità effettiva 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:

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.

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

Richieste batch

Le richieste batch possono migliorare le prestazioni, ma dimensioni del batch più grandi possono attivare la limitazione della frequenza. Non inviare batch superiori a 50 richieste. Per informazioni su come raggruppare le richieste in batch, consulta la sezione Richieste batch.

Argomenti correlati

• Suggerimenti per le prestazioni
• Risolvere i problemi di autenticazione e autorizzazione