Gérer les erreurs d'API

L'API Google Agenda 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, ainsi que des conseils sur la façon de les gérer dans votre application.

Mettre en œuvre l'intervalle exponentiel entre les tentatives

La documentation Google Cloud Storage explique l'intervalle exponentiel entre les tentatives 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, ainsi que les actions suggérées que vous pouvez entreprendre pour la gérer.

400 Bad Request

Erreur d'utilisateur. Cette erreur se produit lorsque vous ne fournissez pas de champ ou de paramètre obligatoire, que vous fournissez une valeur non valide ou que vous fournissez une combinaison de champs non 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, ne réessayez pas. Lisez plutôt le message d'erreur et modifiez votre requête en conséquence.

401 Invalid Credentials

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 à longue durée de vie.
  • Si cela échoue, guidez l'utilisateur dans le flux OAuth, comme décrit dans Autoriser les requêtes avec OAuth 2.0.
  • Si cette erreur se produit pour un compte de service, vérifiez que vous avez bien suivi toutes les étapes de la page du compte de service.

403 User Rate Limit Exceeded

L'une des limites de la console Google Cloud 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 Rate Limit Exceeded

L'utilisateur a atteint le taux de demandes maximal de l'API 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 des codes d'erreur 403 ou 429 . Elles sont fonctionnellement similaires et vous devez les gérer de la même manière, en utilisant un intervalle exponentiel entre les tentatives . Assurez-vous également que votre application suit les bonnes pratiques de la section Gérer les quotas.

403 Calendar usage limits exceeded

L'utilisateur a atteint l'une des limites d'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 :

  • Pour en savoir plus sur les limites d'utilisation d'Agenda, consultez l'aide pour les administrateurs Google Workspace.

403 Forbidden for non-organizer

La requête de mise à jour de l'événement tente de définir l'une des propriétés d'événement partagées dans une copie qui n'est pas celle de l'organisateur. Seul l'organisateur peut définir des propriétés partagées (par exemple, guestsCanInviteOthers, guestsCanModify ou guestsCanSeeOtherGuests).

{
  "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 leurs valeurs par défaut. Envisagez plutôt d'utiliser Events: patch.
  • Si votre requête comporte des propriétés partagées, assurez-vous de ne tenter de modifier ces propriétés que si vous mettez à jour la copie de l'organisateur.

404 Not Found

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é.
  • Lorsque vous accédez à un agenda auquel l'utilisateur ne peut pas accéder.
{
  "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 The requested identifier already exists

Une instance avec l'ID donné 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 la méthode events.update.

409 Conflict

Un élément par lot dans une events.batch opération 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 : Supprimez les éléments terminés et ceux qui ont échoué, puis réessayez les éléments restants dans une autre opération events.batch ou dans des 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 efficacement les ressources. Pour les événements déjà supprimés, aucune autre action n'est nécessaire.

412 Precondition Failed

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 l'entité et réappliquez les modifications. Pour en savoir plus, consultez Obtenir des versions spécifiques de ressources.

429 Too many requests

Une erreur rateLimitExceeded se produit lorsque l'utilisateur a envoyé trop de requêtes dans un délai 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 des codes d'erreur 403 ou 429 . Elles sont fonctionnellement similaires et vous devez les gérer de la même manière, en utilisant un intervalle exponentiel entre les tentatives . Assurez-vous également que votre application suit les bonnes pratiques de la section Gérer les quotas.

500 Backend Error

Une erreur inattendue s'est produite lors du traitement de la requête.

{
  "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.