Gérer les erreurs d'API

L'API Calendar 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.

Le reste de cette page fournit une référence des erreurs d'agenda, avec quelques conseils sur la façon de les gérer dans votre application.

Mettre en œuvre un intervalle exponentiel entre les tentatives

La documentation des API Cloud explique bien le principe de l'algorithme d'interruption exponentielle et comment l'utiliser avec les API Google.

Erreurs et actions suggérées

Cette section fournit la représentation JSON complète de chaque erreur listée et les actions suggérées que vous pouvez entreprendre pour la gérer.

400 Bad Request

Erreur de l'utilisateur. Cela peut signifier qu'un champ ou un paramètre obligatoire n'a pas été fourni, que la valeur fournie n'est pas valide ou que la combinaison de champs fournis n'est pas valide.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

Action suggérée : Comme il s'agit d'une erreur permanente, n'effectuez aucune nouvelle tentative. Lisez plutôt le message d'erreur et modifiez votre demande en conséquence.

401 : Identifiants incorrects

En-tête d'autorisation non valide. Le jeton d'accès que vous utilisez a expiré ou n'est pas valide.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "authError",
    "message": "Invalid Credentials",
    "locationType": "header",
    "location": "Authorization",
   }
  ],
  "code": 401,
  "message": "Invalid Credentials"
 }
}

Actions suggérées :

  • Obtenez un nouveau jeton d'accès à l'aide du jeton d'actualisation de longue durée.
  • Si cela échoue, guidez l'utilisateur dans le flux OAuth, comme décrit dans Autoriser les requêtes avec OAuth 2.0.
  • Si ce message s'affiche pour un compte de service, vérifiez que vous avez bien suivi toutes les étapes de la page du compte de service.

403 : Limite de taux d'utilisateur dépassée

Une des limites de la Developer Console a été atteinte.

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

Actions suggérées :

403 : Fréquence maximale dépassée

L'utilisateur a atteint le nombre maximal de requêtes de l'API Google Agenda par agenda ou par utilisateur authentifié.

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

Action suggérée : Les erreurs rateLimitExceeded peuvent renvoyer les codes d'erreur 403 ou 429. Actuellement, elles sont fonctionnellement similaires et doivent être traitées de la même manière, en utilisant un intervalle exponentiel entre les tentatives. Assurez-vous également que votre application respecte les bonnes pratiques de la section Gérer les quotas.

403 : Limites d'utilisation d'Agenda dépassées

L'utilisateur a atteint l'une des limites de Google Agenda mises en place pour protéger les utilisateurs et l'infrastructure Google contre les comportements abusifs.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

Actions suggérées :

403 : accès interdit pour les utilisateurs autres que l'organisateur

La demande de modification d'un événement tente de définir l'une des propriétés de l'événement partagé dans une copie qui n'est pas celle de l'organisateur. Les propriétés partagées (par exemple, guestsCanInviteOthers, guestsCanModify ou guestsCanSeeOtherGuests) ne peuvent être définies que par l'organisateur.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

Actions suggérées :

  • Si vous utilisez Events: insert, Events: import ou Events: update et que votre requête n'inclut aucune propriété partagée, cela revient à essayer de définir ces propriétés sur leurs valeurs par défaut. Envisagez plutôt d'utiliser Events: patch.
  • Si votre demande comporte des propriétés partagées, assurez-vous de ne les modifier que si vous mettez à jour la copie de l'organisateur.

404 : introuvable

La ressource spécifiée est introuvable. Cela peut se produire dans plusieurs cas. Voici quelques exemples :

  • lorsque la ressource demandée (avec l'ID fourni) n'a jamais existé ;

  • lorsqu'il tente d'accéder à un agenda auquel il n'a pas accès ;

    { "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "Not Found" } ], "code": 404, "message": "Not Found" } }

Action suggérée : utilisez un intervalle exponentiel entre les tentatives.

409 : L'identifiant demandé existe déjà

Une instance avec l'ID indiqué existe déjà dans le stockage.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

Action suggérée : Générez un nouvel ID si vous souhaitez créer une instance. Sinon, utilisez l'appel de méthode update.

409 Conflict

Un élément par lot dans une opération events.batch ne peut pas être exécuté en raison d'un conflit opérationnel avec d'autres éléments par lot demandés.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

Action suggérée : excluez tous les éléments par lot qui ont été traités avec succès et ceux qui ont échoué, puis réessayez les éléments restants dans une autre opération events.batch ou dans les opérations d'événement unique correspondantes.

410 : Gone

Les paramètres syncToken ou updatedMin ne sont plus valides. Cette erreur peut également se produire si une requête tente de supprimer un événement qui a déjà été supprimé.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

ou

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

ou

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

Action suggérée : Pour les paramètres syncToken ou updatedMin, effacez le magasin et resynchronisez-le. Pour en savoir plus, consultez Synchroniser les ressources de manière efficace. Aucune autre action n'est nécessaire pour les événements déjà supprimés.

412 : Échec de la condition préalable

L'etag fourni dans l'en-tête If-match ne correspond plus à l'etag actuel de la ressource.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

Action suggérée : Récupérez à nouveau l'entité et réappliquez les modifications. Pour en savoir plus, consultez Obtenir des versions spécifiques de ressources.

429 : Trop de requêtes

Une erreur rateLimitExceeded se produit lorsque l'utilisateur a envoyé trop de requêtes dans un laps de temps donné.

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

Action suggérée : Les erreurs rateLimitExceeded peuvent renvoyer les codes d'erreur 403 ou 429. Actuellement, elles sont fonctionnellement similaires et doivent être traitées de la même manière, en utilisant un intervalle exponentiel entre les tentatives. Assurez-vous également que votre application respecte les bonnes pratiques de la section Gérer les quotas.

500 : Erreur de backend

Une erreur inattendue s'est produite lors du traitement de la demande.

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

Action suggérée : utilisez un intervalle exponentiel entre les tentatives.