Suivre les erreurs CaptchaAI dans Sentry

Périmètre sûr : ce guide vise vos propres applications ou des systèmes pour lesquels vous détenez une autorisation écrite. Ni sites tiers, ni neutralisation de protections anti-bot.

Dans Sentry, un échec de résolution CAPTCHA ne ressemble pas à une exception : la requête renvoie 200, le token revient vide, et c'est la soumission du formulaire qui casse trois fonctions plus loin. Sans événement propre à l'appel CaptchaAI, la trace désigne le mauvais coupable.

Trois gestes corrigent cela : instrumenter la résolution comme une dépendance externe, la taguer par type de CAPTCHA et par identifiant de tâche, puis séparer la réussite de la résolution de l'acceptation du token.

Ce que Sentry doit recevoir à chaque résolution

Deux tags indexés suffisent ; en empiler davantage rend les recherches illisibles.

Étape 1 : préparer l'environnement avant d'instrumenter

Isolez l'environnement de test, rangez la clé CaptchaAI dans un secret CI, donnez un DSN distinct par environnement. Ajoutez surtout un hook before_send : un CAPTCHA protège une page de connexion ou de paiement, et un payload capturé tel quel embarque des données personnelles — ce filtrage relève de vos obligations RGPD.

Étape 2 : encapsuler l'appel dans une fonction instrumentée

Isolez l'appel dans une seule fonction : elle reçoit le sitekey et l'URL de votre page, renvoie un token, mesure la durée — un seul endroit à instrumenter.

import fetch from 'node-fetch';

const API_KEY = process.env.CAPTCHAAI_KEY;

export async function createTurnstileTask(siteKey, pageUrl) {
  const res = await fetch('https://api.captchaai.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientKey: API_KEY,
      task: {
        type: 'TurnstileTaskProxyless',
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const data = await res.json();
  return data.taskId;
}

Enveloppez ce corps dans un span, avec le taskId en tag : l'événement devient auto-suffisant.

Étape 3 : vérifier le token côté backend, puis mesurer l'écart

Votre backend valide le token avant toute opération métier. Cette vérification produit le signal le plus utile du dispositif : l'écart entre résolutions réussies et tokens acceptés. Un écart qui se creuse sans erreur trahit un token appliqué dans une autre session que celle du défi CAPTCHA.

Seuils d'alerte à câbler

Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée.

Si la latence grimpe sans erreur, regardez l'allocation de threads : la facturation CaptchaAI repose sur les threads simultanés, et BASIC ($15/mois, 5 threads) plafonne à cinq résolutions en vol.

Codes d'erreur à router vers une alerte

Un cas concret : latence nocturne à Lyon

Une équipe e-commerce lyonnaise rejoue chaque nuit ses tests de checkout sur son site, depuis des workers OVHcloud. Sentry a montré une latence qui doublait vers 2 h du matin, quand un export nocturne monopolisait les threads. Décaler l'export a suffi.

Liste de contrôle avant mise en production

• Périmètre limité à vos applications ou à des sources autorisées.
• Clé CaptchaAI absente de tout événement Sentry.
• Hook before_send actif sur les champs personnels.
• Durée, taskId et type de CAPTCHA émis à chaque résolution.

FAQ

Quelles données envoyer à Sentry sans exposer d'informations personnelles ?

Le taskId, le type de CAPTCHA, la durée et le code retour suffisent. Ni le token, ni la clé API, ni le corps du formulaire n'y ont leur place : filtrez-les dans before_send.

Comment distinguer une erreur CaptchaAI d'une erreur applicative ?

Par le titre. Les codes préfixés ERROR_ viennent de l'API et se traitent côté configuration ou solde ; un token accepté puis refusé par votre backend est un problème de session.

Faut-il alerter sur CAPCHA_NOT_READY ?

Non. C'est la réponse normale tant que la tâche est en cours : comptez-la comme métrique de latence, alertez seulement au plafond de polling.

Guides connexes

• démarrage rapide CaptchaAI
• tests CAPTCHA en environnement autorisé
• tester l'endpoint API sur vos formulaires
• résolution CAPTCHA dans votre CI
• résoudre reCAPTCHA v2 via l'API

Instrumentez une fois, diagnostiquez en trois clics. – Créez votre clé CaptchaAI.