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 intercepter 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 spécifiques de l'API Gmail.

Résumé des codes d'état HTTP

Code d'erreur	Description
`200 - OK`	La requête a réussi (il s'agit de la réponse standard pour les requêtes HTTP réussies).
`400 - Bad Request`	La requête ne peut pas être traitée en raison d'une erreur client dans la requête.
`401 - Unauthorized`	La requête contient des identifiants non valides.
`403 - Forbidden`	La requête a été reçue et comprise, mais l'utilisateur n'est pas autorisé à l'exécuter.
`404 - Not Found`	La page demandée est introuvable.
`429 - Too Many Requests`	Trop de requêtes envoyées à l'API.
`500, 502, 503, 504 - Server Errors`	Une erreur inattendue s'est produite lors du traitement de la requête.

Erreurs 400

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

`badRequest`

Cette erreur peut être due à l'un des problèmes suivants 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.
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 corriger 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 est expiré ou non valide. Elle peut également être due à une autorisation manquante pour les champs d'application demandés. 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 à longue durée de vie. Si vous utilisez une bibliothèque cliente, elle gère automatiquement l'actualisation du jeton. 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 situations suivantes :

Votre application ne peut pas être utilisée dans le domaine de l'utilisateur authentifié.
La limite quotidienne a été dépassée.
La limite autorisée par utilisateur a été dépassée.
La limite autorisée par projet a été dépassée.

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

`dailyLimitExceeded`

Cette erreur se produit lorsque la limite de l'API pour votre projet a été atteinte. 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 s'affiche lorsque le propriétaire de l'application a défini une limite de quota pour limiter l'utilisation d'une ressource particulière. Pour corriger cette erreur, augmentez le quota dans le projet Google Cloud. Pour en savoir plus, consultez la section Gérer les limites de quota.

`domainPolicy`

Cette erreur se produit lorsque la règle 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 corriger cette erreur, procédez comme suit :

Informez l'utilisateur que le domaine n'autorise pas votre application à accéder à Gmail.
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 débit maximal de requêtes de l'API Gmail. Cette limite varie en fonction du type de requête. 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 corriger cette erreur, procédez comme suit :

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

`userRateLimitExceeded`

Cette erreur se produit lorsque la limite par utilisateur a été atteinte. 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 corriger cette erreur, essayez d'optimiser le code de votre application afin d'effectuer 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 relançant 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 quelque raison que ce soit. Pour en savoir plus sur les limites, consultez la section 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 gmail.com en version d'essai. Pour connaître ces limites, consultez Limites d'envoi Gmail dans Google Workspace.

Ces limites sont par utilisateur et sont partagées par tous les clients de l'utilisateur, qu'il s'agisse de clients API, de clients intégrés ou Web, ou de MSA SMTP. Si ces limites sont dépassées, une erreur HTTP 429 "Too many requests: User-rate limit exceeded (Mail sending)" (Trop de requêtes : limite autorisée par utilisateur dépassée [envoi d'e-mails]) est renvoyée avec un délai avant la prochaine tentative. Le dépassement des limites quotidiennes peut entraîner ces erreurs pendant plusieurs heures avant que la requête ne soit acceptée.

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 bien été envoyé.

Limites de bande passante

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

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" (Trop de requêtes : limite autorisée par utilisateur dépassée) est renvoyée avec un délai avant la prochaine tentative. Le dépassement des limites quotidiennes peut entraîner ces 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 qui accèdent à un utilisateur et garantit qu'aucun client d'API ne surcharge la boîte aux lettres d'un 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 d'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: Too many concurrent requests for user" (Trop de requêtes : trop de requêtes simultanées pour l'utilisateur) est renvoyée.

Erreurs 500, 502, 503 et 504

Ces erreurs se produisent lorsqu'une erreur de serveur inattendue survient lors du traitement de la requête. Plusieurs problèmes peuvent être à l'origine de ces erreurs, y compris le chevauchement du timing d'une requête avec une autre ou une requête pour une action non compatible, par exemple 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 requête. L'exemple JSON suivant représente cette erreur :

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

Pour corriger cette erreur, utilisez un intervalle exponentiel entre les tentatives pour relancer la requête.

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

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.

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

Requêtes par lot

L'utilisation de requêtes par lot est recommandée. Toutefois, les 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 en savoir plus sur l'exécution de requêtes par lot, consultez Requêtes par lot.