Gestion des erreurs, limitation du débit et gestion des quotas

Lorsque vous interrogez l'API Developer Knowledge ou le serveur MCP Developer Knowledge dans des applications de production et des agents d'IA, vous devez gérer les erreurs et les quotas pour obtenir des performances élevées.

Dans ce guide, vous allez apprendre à :

  • Mettez en œuvre un intervalle exponentiel tronqué entre les tentatives avec gigue pour les réponses HTTP 429.
  • Gérez les codes d'erreur gRPC canoniques (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Gérez les délais d'expiration de la connexion MCP et la logique de nouvelle tentative.
  • Appliquez les bonnes pratiques de gestion des quotas et de mise en cache.

Limitation du débit HTTP 429 et intervalle exponentiel entre les tentatives

Lorsque les taux de requêtes dépassent le quota d'API par défaut, le service renvoie une erreur HTTP 429 Too Many Requests. Les applications doivent implémenter une logique de nouvelle tentative à l'aide d'un intervalle exponentiel tronqué entre les tentatives avec gigue pour éviter de surcharger le service.

Intervalle exponentiel entre les tentatives tronqué

Calculez les délais de réessai à l'aide de la formule suivante :

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

Utilisez les paramètres suivants pour calculer les délais de réessai :

  • initial_delay : délai de première nouvelle tentative (par exemple, 1 seconde).
  • max_delay : limite maximale de l'intervalle entre les tentatives (par exemple, 32 secondes).
  • attempt : nombre actuel de tentatives (0, 1, 2, ...).
  • jitter : valeur aléatoire comprise entre 0 et 1,0 seconde pour éviter les pics de synchronisation des threads (problème de thundering herd).

Gestion des erreurs gRPC

Les applications qui accèdent au service via gRPC doivent inspecter les valeurs grpc.StatusCode canoniques.

Codes d'état gRPC standards

Le tableau suivant répertorie les codes d'état gRPC canoniques renvoyés par le service et la gestion recommandée par le client :

Code d'état gRPC État HTTP Origine du problème Action recommandée
INVALID_ARGUMENT 400 Bad Request Chaîne de requête mal formée, format de paramètre non valide ou masque de champ non valide. Ne pas réessayer Corrigez les paramètres de la requête avant de la répéter.
UNAUTHENTICATED 401 Unauthorized Clé API ou jeton OAuth Bearer manquant, expiré ou mal formé. Ne pas réessayer Actualisez les identifiants ou générez une clé API valide.
PERMISSION_DENIED 403 Forbidden La clé API ne dispose pas des autorisations nécessaires ou l'API Developer Knowledge est désactivée dans le projet. Ne pas réessayer Vérifiez que l'API est activée dans la console Google Cloud.
NOT_FOUND 404 Not Found Le chemin d'accès au document parent spécifié n'existe pas. BatchGetDocuments échoue de manière atomique si l'un des documents demandés est introuvable. Ne pas réessayer Vérifiez le nom de ressource du document.
RESOURCE_EXHAUSTED 429 Too Many Requests La limite de débit ou de quota du projet a été dépassée. Réessayez en utilisant un intervalle exponentiel entre les tentatives avec la gigue.
UNAVAILABLE 503 Service Unavailable Déconnexion réseau temporaire ou redémarrage du serveur. Réessayez avec un intervalle exponentiel entre les tentatives.
DEADLINE_EXCEEDED 504 Gateway Timeout La requête a dépassé le délai RPC configuré avant la fin. Nouvelle tentative avec un délai avant expiration du RPC client plus long.

Gestion des erreurs et du délai d'attente de la connexion MCP

Le serveur MCP Developer Knowledge est un service distant hébergé sur https://developerknowledge.googleapis.com/mcp et accessible via HTTPS (à l'aide de HTTP POST ou d'événements envoyés par le serveur). Les hôtes et agents d'IA doivent gérer les délais avant expiration de la connexion et les erreurs d'outil de manière optimale.

Délai d'expiration de l'exécution de l'outil

Lorsqu'un agent appelle search_documents, get_documents ou answer_query, les appels d'outils peuvent dépasser les délais d'inactivité (par exemple, 30 secondes) si les connexions réseau sont lentes.

Pour gérer les délais d'exécution des outils :

  • Configurer les délais d'expiration du client : définissez les délais d'exécution des outils sur 30 à 60 secondes dans la configuration de votre client hôte MCP.
  • Gérer les interruptions réseau : relancez les requêtes HTTP ayant échoué avec un délai exponentiel en cas de perte de connexion réseau temporaire ou de réponses HTTP 503.
  • Inspectez les messages d'erreur : analysez les messages d'erreur JSON-RPC standards ou les codes d'état d'erreur HTTP pour distinguer les arguments non valides de l'épuisement du quota.

Bonnes pratiques de gestion des quotas

Suivez ces bonnes pratiques pour maintenir une utilisation optimale de l'API et éviter les limites de débit inattendues :

  1. Mettre en cache le contenu des documents récupérés : stockez les documents Markdown récupérés localement ou dans un cache (tel que Redis) lorsque vous créez des applications qui accèdent fréquemment aux mêmes pages.
  2. Utilisez la récupération par lot : utilisez documents.batchGet plutôt que d'exécuter plusieurs requêtes documents.get séquentielles.
  3. Optimisez les champs de requête : ne demandez que les champs de réponse requis à l'aide de masques de champ sélectifs (fields=results(parent,content)).
  4. Surveillez la consommation de quota : suivez les taux de requêtes API dans le tableau de bord des API de la console Google Cloud.

Contenu associé