Corriger les erreurs

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 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 pouvant 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:

  • Vous n'avez pas fourni un champ ou un paramètre obligatoire.
  • 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 résoudre 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 est expiré ou non valide. Cette erreur peut également être due à une autorisation manquante 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 le rafraîchissement du jeton. Si cette opération échoue, guidez l'utilisateur à travers le flux OAuth, comme décrit dans la section Autoriser votre application avec Gmail.

Pour en savoir plus sur les limites Gmail, consultez la section 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 fichier JSON renvoyé. Cette erreur se produit dans les situations suivantes:

  • La limite quotidienne a été dépassée.
  • La limite autorisée 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 Gmail, consultez la section Limites d'utilisation.

Résoudre une erreur 403: limite quotidienne dépassée

Une erreur dailyLimitExceeded indique que la limite d'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 API.
  2. Sélectionnez votre projet.
  3. Cliquez sur l'onglet Quotas.
  4. Demandez un quota supplémentaire. Pour en savoir plus, consultez la section Demander un quota supplémentaire.

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

Résoudre une erreur 403: limite de débit 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 en savoir plus sur la nouvelle tentative des requêtes, consultez la section Renouveler les requêtes qui ont échoué pour résoudre les erreurs.

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

Résoudre une erreur 403: limite de débit dépassée

Une erreur rateLimitExceeded indique que l'utilisateur a atteint le débit 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, renouvelez les requêtes ayant échoué.

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

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

Une erreur domainPolicy se produit lorsque la règle 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: trop de requêtes

Une erreur 429 "Trop de requêtes" peut se produire en raison de limites quotidiennes par utilisateur (y compris des 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 des informations sur chaque limite. Toutefois, chaque limite peut être résolue en essayant de réessayer 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 quelque raison que ce soit. Pour en savoir plus sur les limites, consultez la section Limites d'utilisation.

Limites d'envoi de messages

L'API Gmail applique les limites d'envoi de messages par jour standards. Ces limites diffèrent pour les utilisateurs payants Google Workspace et les utilisateurs Gmail.com d'essai. Pour connaître ces limites, consultez Limites d'envoi Gmail dans Google Workspace.

Ces limites sont définies par utilisateur et sont partagées par tous les clients de l'utilisateur, qu'il s'agisse de clients d'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 débit utilisateur dépassée"(envoi de messages) 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 demande ne soit acceptée.

Le pipeline d'envoi de messages est complexe: une fois que l'utilisateur dépasse son quota, un délai de plusieurs minutes peut être nécessaire avant que l'API 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 dispose de limites de bande passante d'importation et de téléchargement par utilisateur 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 de nouvelle tentative. Notez que le dépassement des limites quotidiennes peut entraîner ces types d'erreurs 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 garantit qu'aucun client d'API ne surcharge une boîte aux lettres d'utilisateur Gmail ni son serveur backend.

L'envoi de nombreuses requêtes parallèles pour un seul utilisateur ou l'envoi de lots contenant un grand nombre de requêtes peut déclencher cette erreur. Un grand nombre de clients API indépendants accédant simultanément à la boîte aux lettres de l'utilisateur Gmail peut également déclencher cette erreur. Si cette limite est dépassée, une erreur HTTP 429 Too Many Requests "Trop de requêtes simultanées pour l'utilisateur" est renvoyée.

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, renouvelez les requêtes ayant échoué. Voici une liste d'erreurs 500:

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

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 une requête ayant échoué au bout d'une seconde, puis de deux secondes, puis de 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 avec simultanéité.

Démarrez 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 la méthode de traitement par lot est recommandée. Toutefois, les tailles de lot plus importantes sont susceptibles de déclencher la limitation de débit. Il est déconseillé d'envoyer des lots de plus de 50 requêtes. Pour savoir comment effectuer des requêtes par lot, consultez la section Effectuer des requêtes par lot.