Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections anti-bot.
Dans un serveur Axum, résoudre un CAPTCHA se résume à un appel HTTPS asynchrone : votre service envoie les paramètres du défi à l'API CaptchaAI, récupère un token, puis l'injecte dans la requête qui poursuit le parcours. Tout le reste — secrets, observabilité, gestion des erreurs — sert à rendre ce flux stable quand il tourne sans surveillance, en job planifié ou en worker interne. Ce guide couvre l'intégration sur la pile async de Rust, du premier appel aux métriques de production.
Architecture : comment Axum appelle CaptchaAI
Un handler Axum — ou, mieux, une tâche de fond découplée de la requête entrante — construit la charge utile attendue par le solveur, l'envoie à CaptchaAI et attend le token. Comme Axum s'appuie sur Tokio, cet appel doit rester non bloquant : utilisez un client HTTP async (reqwest, par exemple), jamais un client synchrone qui figerait le runtime. Isolez cette logique dans un module dédié plutôt que de la disperser dans vos handlers : vous obtenez un point unique où tracer chaque étape.
Le flux de résolution, étape par étape
La séquence est identique pour reCAPTCHA v2, Turnstile ou une image OCR ; seul le contenu de la tâche change.
- Capturez exactement les bons paramètres. N'extrayez que ce que le type de CAPTCHA attend : le sitekey, l'URL de la page, l'action éventuelle, un proxy si nécessaire. Stocker plus crée de fausses pistes de débogage.
- Envoyez la tâche à l'API, puis traitez tout statut inattendu comme une erreur : journalisez la réponse complète et remontez-la vers votre supervision.
- Interrogez le résultat (polling) à intervalle régulier, avec un plafond strict par tâche. Une interrogation trop agressive ajoute du bruit ; trop lâche, elle ralentit le parcours.
- Appliquez le token dans la même session que celle qui a déclenché le défi : même contexte, même client HTTP, même jeu de cookies. Pour Turnstile, le champ à renseigner est
cf-turnstile-response. Une session dépareillée est la première cause de rejet. - Mesurez la latence, les retries et l'acceptation en aval. La réussite du solveur et celle du parcours sont deux métriques distinctes.
Exemple d'appel côté serveur
Le module ci-dessous construit une tâche Turnstile dans votre service. Le contrat envoi/interrogation ne change pas d'un langage à l'autre : compris en Node.js, il se transpose vers un client async en Rust.
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;
}
Une seconde fonction interroge le résultat, récupère le token et le renvoie au handler qui poursuit la soumission.
Gérer les secrets et la configuration
La clé API CaptchaAI ne doit jamais vivre dans le code ni dans un fichier versionné. Rangez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de CI, et montez-la en variable d'environnement au démarrage ; sur OVHcloud ou Scaleway, elle passe par les secrets de la plateforme de conteneurs. Prévoyez une vérification au boot : si la variable est absente, faites échouer le serveur avec un message clair plutôt que de renvoyer une erreur d'authentification à la première résolution.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Ces signaux alimentent vos tableaux de bord et vos alertes.
Journaux par environnement et RGPD
Séparez les logs par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouerez un scénario complet depuis un identifiant unique et réduirez le temps de diagnostic. Côté conformité, appliquez la minimisation — ne journalisez pas de données personnelles superflues et vérifiez vos obligations RGPD avant de conserver des payloads complets.
Mesurer la réussite de l'intégration
Câblez ces indicateurs dans le tableau de bord que vous utilisez déjà :
- Latence de résolution (p50 et p95) — une médiane stable et une queue contenue montrent que vos timeouts sont bien dimensionnés.
- Taux de réussite du solveur par type de CAPTCHA — une chute sur une famille précise trahit souvent de mauvais paramètres d'entrée.
- Acceptation en aval après injection du token — un token résolu n'est pas un parcours réussi ; suivez séparément le statut HTTP après soumission.
- Coût par résolution acceptée — s'il dérive, ce sont les boucles de mauvais paramètres et les retries en rafale qui érodent la marge.
Gardez le modèle de coût en tête : CaptchaAI facture au thread simultané, pas à la résolution. Le plan BASIC ($15/mois, 5 threads) inclut déjà des résolutions illimitées sur ces threads. Votre débit dépend donc du nombre de threads et de la vitesse par type, pas d'un tarif par CAPTCHA.
Liste de contrôle avant mise en production
- La clé CaptchaAI est dans un coffre ou un secret de CI, jamais dans le code.
- Le client HTTP est asynchrone : aucun appel bloquant dans un handler Axum.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Un retry idempotent à backoff exponentiel borné couvre les erreurs transitoires.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Token appliqué dans une session différente du défi. | Gardez résolution et soumission dans le même contexte HTTP. |
| Le runtime se fige | Client HTTP synchrone dans un handler async. | Passez à un client async (reqwest), non bloquant. |
ERROR_ZERO_BALANCE |
Solde insuffisant. | Rechargez et ajoutez une alerte de solde. |
| Polling qui expire | Plafond trop bas ou pic de charge. | Ajustez le plafond par tâche et appliquez un backoff. |
| Clé absente au runtime | Secret non monté dans l'environnement. | Vérifiez la variable au démarrage et faites échouer le boot. |
FAQ
Faut-il un client HTTP asynchrone dans Axum ?
Oui. Axum tourne sur Tokio ; un appel bloquant vers l'API figerait le runtime et pénaliserait toutes les requêtes en cours. Utilisez un client async comme reqwest pour ne jamais bloquer le handler.
Puis-je réutiliser cette logique pour un autre type de CAPTCHA ?
Oui. La séquence envoi/interrogation/injection reste identique pour reCAPTCHA v2, Turnstile ou une image OCR : vous ne changez que le contenu de la tâche et le champ de token attendu par la page.
Que faire en cas d'erreur transitoire de l'API ?
Mettez en place un retry avec backoff exponentiel borné (trois tentatives, délai doublé à chaque essai, plafond à 30 secondes). Tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez la configuration réseau et les quotas associés à votre clé.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
