Gestion des Erreurs

L'exécution d'une capacité comporte deux canaux d'échec, et gérer les deux fait la différence entre un agent qui se rétablit et un agent qui plante.

Vérifier l'échec d'une capacité comme données renvoyées

Une exécution résolue avec isError: true signifie que la requête s'est terminée et que le connecteur a signalé une action en échec. C'est un résultat, pas une exception levée ; votre boucle d'agent peut donc renvoyer le texte de l'erreur au modèle et le laisser se rétablir :

const result = await capability.execute(args, { idempotencyKey });

if (result.isError) {
  const text = result.content.map((part) => part.text).join('\n');
  // return the text to the model as the tool result
}

Affiner les erreurs levées, de la plus spécifique à la plus générale

Tout ce qui se trouve en dehors des résultats de capacité (authentification, HTTP, validation, limite de débit, quota, timeout, réseau, configuration) lève une exception :

import {
  VinkiusError,
  AuthError,
  RateLimitError,
  QuotaError,
  ConnectorNotConnectedError,
} from '@vinkius/connect';

try {
  const result = await capability.execute(args, { idempotencyKey });
  if (result.isError) {
    // connector-level failure: feed result.content back to the model
  }
} catch (error) {
  if (error instanceof ConnectorNotConnectedError) {
    // send the user through the connector setup flow
  } else if (error instanceof RateLimitError) {
    // back off using the response's retry information
  } else if (error instanceof QuotaError || error instanceof OverageError) {
    // plan limit reached: surface an upgrade path
  } else if (error instanceof AuthError) {
    // application key rejected: check rotation and environment
  } else if (error instanceof VinkiusError) {
    // any other API error
  } else {
    // hooks can throw their own errors; keep an unknown branch
  }
}

Chaque VinkiusError possède code, status, requestId et details. Les erreurs locales et de transport utilisent l'état 0. requestId n'est présent que lorsque le serveur en a fourni un.

La taxonomie des erreurs

Savoir quelles requêtes le SDK répète

Le maximum par défaut est la tentative initiale plus deux nouvelles tentatives. Les erreurs réseau, les timeouts et les réponses HTTP 429, 502, 503 ou 504 sont considérés comme transitoires, mais seules les requêtes répétables sont retentées : GET, PUT et DELETE par défaut ; la création d'utilisateur et la création de connexion parce que leurs contrats sont des upsert/get-or-create ; et l'exécution d'une capacité uniquement lorsqu'une idempotencyKey est fournie.

Générer et valider les clés d'exécution dans votre application

Le transport traite une clé d'idempotence undefined comme « pas de nouvelle tentative » et n'envoie l'en-tête Idempotency-Key que pour une chaîne truthy. Une chaîne vide active donc les nouvelles tentatives sans envoyer l'en-tête. Dérivez les clés de l'opération logique, validez qu'elles ne sont pas vides et réutilisez une clé uniquement pour retenter cette même opération :

const key = `create-issue:${operationId}`;
if (!key.trim()) throw new Error('idempotency key required');

Ne pas compter sur le dispatch d'un adaptateur pour les options d'exécution

Les fonctions utilitaires de dispatch et les fonctions liées par une fabrique d'adaptateur appellent capability.execute(args) sans ExecuteOptions : pas de clé, pas de signal de l'appelant, une seule tentative de transport. Les noms inconnus transmis aux dispatchers d'adaptateurs lèvent une simple Error, et non une VinkiusError. Résolvez la Capability et appelez execute() directement lorsque vous avez besoin d'annulation ou d'idempotence.

Enregistrer les diagnostics sans enregistrer de secrets

try {
  // ...
} catch (error) {
  if (error instanceof VinkiusError) {
    logger.error({ code: error.code, status: error.status, requestId: error.requestId });
  }
  throw error;
}

Les hooks d'observabilité reçoivent des vues expurgées (en-têtes d'autorisation et noms de champs de secrets connus retirés), mais votre propre journalisation doit toujours traiter les valeurs d'identifiants soumises comme des secrets. Les callbacks de hook peuvent lever leurs erreurs d'origine, et un abandon pendant le délai entre les nouvelles tentatives peut propager directement la raison du signal. Conservez une branche finale unknown au lieu de supposer que toute valeur levée est une VinkiusError.

Étapes suivantes

• Understand the architecture behind error handling
• Execute with idempotency and cancellation
• Keep the application key server-side