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.

Les applications Gmail doivent détecter et gérer toutes les erreurs qui peuvent survenir lors de l'utilisation de l'API REST. Ce guide explique comment résoudre des erreurs d'API spécifiques.

Résoudre une erreur 400 : requête incorrecte

Cette erreur peut être due aux erreurs suivantes dans votre code :

  • Un champ ou un paramètre obligatoire n'a pas été fourni.
  • La valeur fournie ou une combinaison de champs fournis 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 à une autorisation manquante pour les niveaux d'accès 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 du jeton. Si cela échoue, guidez l'utilisateur dans le flux OAuth, comme décrit dans 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 a été 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 JSON renvoyé. Cette erreur se produit dans les situations suivantes :

  • La limite quotidienne a été dépassée.
  • La limite de débit par utilisateur a été dépassée.
  • 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 de l'API de courtoisie pour votre projet a été atteinte. 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 :

  1. Accédez à la console Google APIs.
  2. Sélectionnez votre projet.
  3. Cliquez sur l'onglet Quotas.
  4. Demandez un quota supplémentaire. Pour en savoir plus, consultez Demander une augmentation de quota.

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

Résoudre une erreur 403 : limite autorisée par 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 de réduire le nombre de requêtes ou de réessayer les requêtes. Pour savoir comment renouveler les demandes, consultez Renouveler les demandes qui ont échoué pour résoudre les erreurs.

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

Résoudre une erreur 403 : "Limitation du débit 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 demandes. 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, renouvelez les demandes qui ont échoué.

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

Résoudre une erreur 403 : l'application portant l'ID {appId} ne peut pas être utilisée dans le domaine de l'utilisateur authentifié

Une erreur domainPolicy se produit lorsque le règlement du domaine de l'utilisateur n'autorise pas l'accès à Gmail par votre application. Vous trouverez ci-dessous 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 :

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

Résoudre une erreur 429 : "Too Many Requests"

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 de 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 essayant de réexécuter les requêtes ayant échoué ou en répartissant le traitement sur plusieurs comptes Gmail. Les limites par utilisateur ne peuvent être augmentées pour aucune raison. 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 diffèrent pour les utilisateurs Google Workspace payants et les utilisateurs d'essai gmail.com. Pour connaître ces limites, consultez Limites d'envoi Gmail dans Google Workspace.

Ces limites s'appliquent par utilisateur et sont partagées par tous les clients de l'utilisateur, qu'il s'agisse de clients API, de clients natifs/Web ou de MSA SMTP. Si ces limites sont dépassées, une erreur HTTP 429 Too Many Requests "Limite de fréquence utilisateur dépassée"(envoi d'e-mails) est renvoyée avec le délai avant nouvelle tentative. Notez que le dépassement des limites quotidiennes peut entraîner ce type d'erreur pendant plusieurs heures avant que la demande ne soit acceptée.

Le pipeline d'envoi de 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 donc 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 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 "Limite de débit utilisateur dépassée" est renvoyée avec un délai avant nouvelle tentative. Notez que le dépassement des limites quotidiennes peut entraîner ce type d'erreur pendant plusieurs heures avant que la demande 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 qui accèdent à un utilisateur donné. 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.

Cette erreur peut se produire 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 cette limite est dépassée, l'erreur HTTP 429 Too Many Requests "Too many concurrent requests for user" (Trop de requêtes simultanées pour l'utilisateur) est renvoyée.

Résoudre une erreur 500 : erreur de backend

Une backendError se produit lorsqu'une erreur inattendue survient lors du traitement de la demande.

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

Pour corriger cette erreur, renouvelez les demandes qui ont échoué. Voici une liste d'erreurs 500 :

  • 502 Passerelle incorrecte
  • 503 Service indisponible.
  • 504 Expiration du délai de la passerelle

Renouveler les demandes qui ont é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.

Afficher ou modifier les limites d'utilisation, 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 :

  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.

Requêtes par lot

L'utilisation de lots est encouragée, mais les tailles de lot plus importantes sont susceptibles de déclencher une limitation du débit. Il est déconseillé d'envoyer des lots de plus de 50 requêtes. Pour savoir comment regrouper des requêtes par lot, consultez Effectuer des requêtes par lot.