L'API Gmail renvoie deux niveaux d'informations d'erreur:
- Codes et messages d'erreur HTTP dans l'en-tête.
- Un objet JSON dans le corps de la réponse avec des détails supplémentaires qui peuvent vous aider à déterminer comment gérer l'erreur.
Les applications Gmail doivent détecter et gérer toutes les erreurs pouvant survenir lors de l'utilisation de l'API REST. Ce guide fournit des instructions pour résoudre des erreurs d'API spécifiques.
Résoudre une erreur 400: requête incorrecte
Cette erreur peut être due aux erreurs suivantes à votre code:
- Un champ ou un paramètre obligatoire n'a pas été renseigné.
- La valeur indiquée ou une combinaison de champs indiqués n'est pas valide.
- Pièce jointe non valide.
Voici un exemple de représentation JSON de cette erreur:
{
"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."
}
}
Pour corriger cette erreur, vérifiez le champ message et ajustez votre code en conséquence.
Résoudre une erreur 401: identifiants non valides
Une erreur 401 indique que le jeton d'accès que vous utilisez a expiré ou n'est pas valide. Cette erreur peut également être due à un manque d'autorisation pour les champs d'application demandés. Voici la représentation JSON de cette erreur:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Pour corriger cette erreur, actualisez le jeton d'accès à l'aide du jeton d'actualisation de longue durée. Si vous utilisez une bibliothèque cliente, elle gère automatiquement l'actualisation des jetons. Si cette opération échoue, dirigez l'utilisateur via le flux OAuth, comme décrit dans la section Autoriser votre application avec Gmail.
Pour en savoir plus sur les limites de Gmail, consultez Limites d'utilisation.
Résoudre une erreur 403: limite d'utilisation dépassée
Une erreur 403 se produit lorsqu'une limite d'utilisation est dépassée ou que l'utilisateur ne dispose pas des droits appropriés. Pour déterminer le type d'erreur spécifique, évaluez le champ reason du fichier JSON renvoyé. Cette erreur se produit dans les situations suivantes:
- La limite quotidienne a été dépassée.
- Le nombre maximal d'utilisateurs a été dépassé.
- La limite de débit du projet a été dépassée.
- Votre application ne peut pas être utilisée dans le domaine de l'utilisateur authentifié.
Pour en savoir plus sur les limites de Gmail, consultez Limites d'utilisation.
Résoudre une erreur 403: limite quotidienne dépassée
Une erreur dailyLimitExceeded indique que la limite d'API de courtoisie a été atteinte pour votre projet. Voici la représentation JSON de cette erreur:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Solution :
- Accédez à la console Google APIs.
- Sélectionnez votre projet.
- Cliquez sur l'onglet Quotas.
- Demandez un quota supplémentaire. Pour en savoir plus, consultez la section Demander une augmentation de quota.
Pour en savoir plus sur les limites de Gmail, consultez Limites d'utilisation.
Résoudre une erreur 403: limite de fréquence utilisateur dépassée
Une erreur userRateLimitExceeded indique que la limite par utilisateur a été atteinte. Voici la représentation JSON de cette erreur:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Pour corriger cette erreur, essayez d'optimiser le code de votre application afin d'effectuer moins de requêtes ou de relancer les requêtes. Pour en savoir plus, consultez la section Relancer les requêtes ayant échoué pour résoudre les erreurs.
Pour en savoir plus sur les limites de Gmail, consultez Limites d'utilisation.
Résoudre une erreur 403: fréquence limite dépassée
Une erreur rateLimitExceeded indique que l'utilisateur a atteint le taux de requêtes maximal de l'API Gmail. Cette limite varie en fonction du type de requêtes.
Voici la représentation JSON de cette erreur:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Pour corriger cette erreur, réessayez les requêtes ayant échoué.
Pour en savoir plus sur les limites de Gmail, consultez Limites d'utilisation.
Corriger une erreur 403: impossible d'utiliser l'application associée à l'ID {appId} dans le domaine de l'utilisateur authentifié
Une erreur domainPolicy se produit lorsque la règle pour le domaine de l'utilisateur n'autorise pas votre application à accéder à Gmail. Voici la représentation JSON de cette erreur:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "domainPolicy",
"message": "The domain administrators have disabled Gmail apps."
}
],
"code": 403,
"message": "The domain administrators have disabled Gmail apps."
}
}
Solution :
- Informez l'utilisateur que le domaine n'autorise pas votre application à accéder à Gmail.
- Demandez à l'utilisateur de contacter l'administrateur du domaine pour demander l'accès à votre application.
Résoudre une erreur 429: trop de requêtes
Une erreur 429 "Trop de requêtes" peut se produire en raison de limites quotidiennes par utilisateur (y compris les limites d'envoi de messages), de limites de bande passante ou d'une limite de requêtes simultanées par utilisateur. Vous trouverez ci-dessous les informations relatives à chaque limite. Cependant, chaque limite peut être résolue en tentant de relancer les requêtes ayant échoué ou en répartissant le traitement sur plusieurs comptes Gmail. Les limites par utilisateur ne peuvent pas être augmentées pour une raison quelconque. Pour en savoir plus sur les limites, consultez la section Limites d'utilisation.
Limites d'envoi de messages
L'API Gmail applique les limites quotidiennes standards d'envoi de messages. Ces limites diffèrent pour les utilisateurs payants Google Workspace et pour les utilisateurs d'essai gmail.com. Pour connaître ces limites, consultez la section Limites d'envoi Gmail dans Google Workspace.
Ces limites sont définies au niveau de l'utilisateur et sont partagées par tous les clients de l'utilisateur, qu'il s'agisse des clients API, natifs/Web ou MSA SMTP. Si ces limites sont dépassées, une erreur HTTP 429 Too Many Requests "User-rate limit exceeded" (Limite de débit utilisateur dépassée) "(Mail send)" est renvoyée avec le délai de nouvelle tentative.
Notez que le dépassement des limites quotidiennes peut entraîner ces types d'erreurs pendant plusieurs heures avant que la requête ne soit acceptée.
Le pipeline d'envoi de messages est complexe: une fois que l'utilisateur a dépassé son quota, il peut s'écouler plusieurs minutes avant que l'API ne commence à renvoyer des réponses d'erreur 429. Vous ne pouvez donc pas supposer qu'une réponse 200 signifie que l'e-mail a bien été envoyé.
Limites de bande passante
L'API impose des limites de bande passante par utilisateur pour l'importation et le téléchargement. Ces limites sont égales, mais indépendantes de l'accès IMAP. Ces limites sont partagées entre tous les clients de l'API Gmail d'un utilisateur donné.
Ces limites ne sont généralement atteintes que dans des situations exceptionnelles ou abusives.
Si ces limites sont dépassées, une erreur HTTP 429 Too Many Requests
"User-rate limit exceeded" (Limite de débit utilisateur dépassée) est renvoyée avec un délai de nouvelle tentative.
Notez que le dépassement des limites quotidiennes peut entraîner ces types d'erreurs pendant plusieurs heures avant que la requête ne soit acceptée.
Requêtes simultanées
L'API Gmail applique une limite de requêtes simultanées par utilisateur (en plus de la limite de débit par utilisateur). Cette limite est partagée par tous les clients de l'API Gmail accédant à un utilisateur donné et garantit qu'aucun client API ne surcharge la boîte aux lettres d'un utilisateur Gmail ou son serveur backend.
L'envoi de nombreuses requêtes parallèles pour un seul utilisateur ou l'envoi de lots avec un grand nombre de requêtes peuvent déclencher cette erreur. Un grand nombre de clients API indépendants accédant simultanément à la boîte aux lettres utilisateur Gmail peuvent également déclencher cette erreur. Si cette limite est dépassée, une erreur HTTP 429 Too Many Requests s'affiche : "Trop de requêtes simultanées pour l'utilisateur".
Résoudre une erreur 500: erreur de backend
Une erreur backendError se produit lorsqu'une erreur inattendue se produit lors du traitement de la requête.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Pour corriger cette erreur, réessayez les requêtes ayant échoué. Voici une liste des erreurs 500:
- 502 Passerelle incorrecte
- 503 Service indisponible.
- 504 Expiration du délai de la passerelle
Relancer les requêtes ayant échoué pour résoudre les erreurs
Vous pouvez relancer régulièrement une requête ayant échoué sur une durée croissante pour gérer les erreurs liées aux limites de débit, au volume du réseau ou au temps de réponse. Par exemple, vous pouvez relancer une requête ayant échoué après une seconde, puis deux, et enfin quatre secondes. Cette méthode est appelée intervalle exponentiel entre les tentatives. Elle permet d'améliorer l'utilisation de la bande passante et de maximiser le débit des requêtes dans les environnements simultanés.
Commencez les périodes de nouvelle tentative au moins une seconde après l'erreur.
Afficher ou modifier les limites d'utilisation et augmenter le quota
Pour afficher ou modifier les limites d'utilisation de votre projet, ou pour demander une augmentation des quotas, procédez comme suit :
- Si vous ne possédez pas encore de compte de facturation pour votre projet, créez-en un.
- Accédez à la page "API activées" de la bibliothèque d'API dans la console APIs, puis sélectionnez une API dans la liste.
- Sélectionnez Quotas pour afficher et modifier les paramètres associés aux quotas. Pour afficher les statistiques d'utilisation, sélectionnez Utilisation.
Requêtes par lot
L'utilisation du traitement par lot est recommandée, mais des tailles de lot plus importantes sont susceptibles de déclencher une limitation du débit. Il n'est pas recommandé d'envoyer des lots de plus de 50 requêtes. Pour plus d'informations sur l'envoi de requêtes par lot, consultez la section Traiter des requêtes par lot.