Corriger les erreurs

L'API Gmail renvoie deux niveaux d'informations sur les erreurs :

• Codes et messages d'erreur HTTP dans l'en-tête.
• Objet JSON dans le corps de la réponse, contenant des informations supplémentaires qui peuvent vous aider à déterminer comment gérer l'erreur.

Votre application Gmail doit détecter et gérer toutes les erreurs que vous rencontrez lorsque vous utilisez l'API REST. Ce guide explique comment résoudre des erreurs spécifiques de l'API Gmail.

Récapitulatif des codes d'état HTTP

Erreurs 400

Ces erreurs indiquent que la requête comporte une erreur, souvent due à un paramètre obligatoire manquant.

badRequest

Cette erreur peut se produire en raison de l'un des problèmes suivants dans votre code :

• Un champ ou un paramètre obligatoire est manquant.
• Une valeur ou une combinaison de champs fournies n'est pas valide.
• La pièce jointe n'est pas valide.

L'exemple JSON suivant représente 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 résoudre cette erreur, vérifiez le champ message et ajustez votre code en conséquence.

Erreurs 401

Ces erreurs signifient que la requête ne contient pas de jeton d'accès valide.

authError

Cette erreur se produit lorsque le jeton d'accès que vous utilisez a expiré ou n'est pas valide. Cette erreur peut également se produire si l'autorisation pour les niveaux d'accès demandés est manquante. L'exemple JSON suivant représente 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 cela échoue, redirigez l'utilisateur vers le flux OAuth, comme décrit dans En savoir plus sur l'authentification et l'autorisation.

Pour en savoir plus sur les limites de Gmail, consultez Limites d'utilisation.

Erreurs 403

Ces erreurs se produisent lorsque vous dépassez une limite d'utilisation ou que l'utilisateur ne dispose pas des droits appropriés. Pour déterminer la cause, évaluez le champ reason du JSON renvoyé. Cette erreur se produit dans les cas suivants :

• Votre application ne peut pas être utilisée dans le domaine de l'utilisateur authentifié.
• Le projet a dépassé la limite quotidienne.
• L'utilisateur a dépassé la limite de débit.
• Le projet a dépassé la limite de fréquence.

Pour en savoir plus, consultez la section Limites d'utilisation.

dailyLimitExceeded

Cette erreur se produit lorsque votre projet atteint sa limite d'API. L'exemple JSON suivant représente cette erreur :

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

Cette erreur se produit lorsque le propriétaire de l'application définit une limite de quota pour plafonner l'utilisation d'une ressource particulière. Pour corriger cette erreur, augmentez le quota dans le projet Google Cloud. Pour en savoir plus, consultez Gérer les limites de quota.

domainPolicy

Cette erreur se produit lorsque le règlement du 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."
  }
}

Pour résoudre cette erreur, procédez comme suit :

1. Informez l'utilisateur que le domaine n'autorise pas votre application à accéder à Gmail.
2. Demandez à l'utilisateur de contacter l'administrateur de son domaine pour demander l'accès à votre application.

rateLimitExceeded

Cette erreur indique que l'utilisateur a atteint le taux de demandes maximal pour l'API Gmail. Cette limite varie en fonction du type de demande. L'exemple JSON suivant représente cette erreur :

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

Pour résoudre cette erreur, procédez comme suit :

• Demandez une augmentation de quota.
• Utilisez un intervalle exponentiel entre les tentatives pour relancer la requête.

userRateLimitExceeded

Cette erreur se produit lorsqu'une requête atteint la limite par utilisateur. L'exemple JSON suivant représente cette erreur :

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

Pour résoudre cette erreur, essayez d'optimiser le code de votre application afin d'envoyer moins de requêtes ou utilisez un intervalle exponentiel entre les tentatives pour relancer la requête.

Erreurs 429

Une erreur 429 "Too many requests" (Trop de requêtes) peut se produire en raison de limites quotidiennes par utilisateur (y compris les limites d'envoi d'e-mails), de limites de bande passante ou d'une limite de requêtes simultanées par utilisateur. Vous trouverez ci-dessous des informations sur chaque limite. Toutefois, chaque limite peut être résolue en réessayant les requêtes ayant échoué ou en répartissant le traitement sur plusieurs comptes Gmail.

Vous ne pouvez pas augmenter les limites par utilisateur. Pour en savoir plus sur les limites, consultez Limites d'utilisation.

Limites d'envoi d'e-mails

L'API Gmail applique les limites d'envoi d'e-mails quotidiennes standards. Ces limites sont différentes pour les utilisateurs payants de Google Workspace et les utilisateurs de la version d'essai de gmail.com. Pour connaître ces limites, consultez Limites d'envoi Gmail dans Google Workspace.

Ces limites s'appliquent à chaque utilisateur et sont partagées par tous ses clients, qu'il s'agisse de clients API, de clients Web ou intégrés, ou de MSA SMTP. Si vous dépassez ces limites, l'API renvoie une erreur HTTP 429 "Too many requests: User-rate limit exceeded (Mail sending)" (Trop de requêtes : limite de débit utilisateur dépassée (envoi d'e-mails)) avec un délai avant nouvelle tentative. Si vous dépassez les limites quotidiennes, ces erreurs peuvent s'afficher pendant plusieurs heures avant que le serveur n'accepte la requête.

Le pipeline d'envoi d'e-mails 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 pas supposer qu'une réponse 200 signifie que l'e-mail a été envoyé avec succès.

Limites de bande passante

L'API est soumise à des limites de bande passante par utilisateur pour les importations et les téléchargements, qui sont égales à celles d'IMAP, mais indépendantes. Ces limites sont partagées entre tous les clients de l'API Gmail pour un utilisateur.

Les utilisateurs ne rencontrent généralement ces limites que dans des situations exceptionnelles ou abusives. Si vous dépassez ces limites, l'API renvoie une erreur HTTP 429 "Too many requests: User-rate limit exceeded" (Trop de requêtes : limite de débit utilisateur dépassée) avec un délai avant nouvelle tentative. Le dépassement des limites quotidiennes peut entraîner ces erreurs pendant plusieurs heures avant que le serveur n'accepte la demande.

Requêtes simultanées

L'API Gmail applique une limite de requêtes simultanées par utilisateur (en plus de la limite de fréquence par utilisateur). Cette limite est partagée par tous les clients de l'API Gmail qui accèdent à un utilisateur. Elle permet de s'assurer qu'aucun client d'API ne surcharge la boîte aux lettres Gmail d'un utilisateur ni son serveur backend.

Ce message d'erreur peut s'afficher si vous envoyez de nombreuses requêtes parallèles pour un même utilisateur ou des lots contenant un grand nombre de requêtes. Un grand nombre de clients API indépendants accédant simultanément à la boîte aux lettres Gmail d'un utilisateur peut également déclencher cette erreur. Si vous dépassez cette limite, l'API renvoie une erreur HTTP 429 "Too many requests: Too many concurrent requests for user" (Trop de requêtes : trop de requêtes simultanées pour l'utilisateur).

Erreurs 500, 502, 503 et 504

Ces erreurs se produisent lorsqu'une erreur de serveur inattendue survient lors du traitement de la requête. Ces erreurs peuvent être dues à différents problèmes, par exemple au fait qu'une requête se chevauche avec une autre ou qu'une requête concerne une action non prise en charge, comme une tentative de mise à jour des autorisations pour une seule page dans Google Sites au lieu de l'ensemble du site.

Voici une liste des erreurs 5xx :

• 500 Erreur de backend
• 502 : passerelle incorrecte
• 503 Service indisponible
• 504 Expiration du délai de la passerelle

backendError

Cette erreur se produit lorsqu'une erreur inattendue survient lors du traitement de la demande. L'exemple JSON suivant représente cette erreur :

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

Pour résoudre ce problème, utilisez un intervalle exponentiel entre les tentatives pour relancer la requête.

Réessayer les requêtes ayant échoué pour résoudre les erreurs

Vous pouvez relancer périodiquement une requête ayant échoué sur une durée de plus en plus longue 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 réessayer d'envoyer une requête ayant échoué après une seconde, puis après deux secondes, puis après 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 d'optimiser le débit des requêtes dans les environnements avec simultanéité.

Commencez les périodes de nouvelle tentative au moins une seconde après l'erreur.

Gérer les limites de quota

Pour afficher ou modifier les limites d'utilisation de votre projet, ou pour demander une augmentation des quotas, procédez comme suit :

1. Si vous ne possédez pas encore de compte de facturation pour votre projet, créez-en un.
2. 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.
3. Sélectionnez Quotas pour afficher et modifier les paramètres associés aux quotas. Pour afficher les statistiques d'utilisation, sélectionnez Utilisation.

Pour en savoir plus, consultez Afficher et gérer les quotas.

Requêtes par lot

Les requêtes par lot peuvent améliorer les performances, mais les tailles de lot plus importantes peuvent déclencher une limitation du débit. N'envoyez pas de lots de plus de 50 requêtes. Pour savoir comment regrouper des requêtes par lot, consultez Requêtes par lot.

Articles associés

• Conseils sur les performances
• Résoudre les problèmes d'authentification et d'autorisation